charieswei
/
vibe-coding-cn
mirror of https://github.com/tukuaiai/vibe-coding-cn.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

refactor: 移除 i18n 层级，将 zh 内容展开到根目录 

- 删除 i18n/en/ 英文版本
- 将 i18n/zh/ 下的 documents/, prompts/, skills/, workflow/ 移至根目录
- 更新所有 i18n/zh/ 路径引用
- 更新 AGENTS.md 目录结构说明
This commit is contained in:
tukuaiai 2026-02-12 01:53:17 +08:00
parent f6342f7e62
commit 37e4abfe89
701 changed files with 105 additions and 264295 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
AGENTS.md
View File

@ -7,7 +7,7 @@
## 1. Mission & Scope（目标与边界）
### 允许的操作
- 读取、修改 `i18n/`、`libs/` 下的文档与代码
- 读取、修改 `documents/`、`prompts/`、`skills/`、`libs/` 下的文档与代码
- 执行 `make lint`、备份脚本、prompts-library 转换工具
- 新增/修改提示词、技能、文档
- 提交符合规范的 commit
@ -79,12 +79,11 @@ git push
### 架构原则
- 保持根目录扁平，避免巨石文件
- 多语言资产统一放在 `i18n/<lang>/` 下，遵循三层结构（documents / prompts / skills）
- 新增语言遵循现有目录层级
- 三层内容架构：`documents/` (知识) → `prompts/` (指令) → `skills/` (能力)
### 模块边界
- `i18n/zh/` - 中文主语料（默认）
- `i18n/en/` - 英文版本
- `` - 中文主语料（默认）
- `` - 英文版本
- `libs/common/` - 通用模块
- `libs/external/` - 外部工具与依赖
@ -146,31 +145,27 @@ git push
│ ├── FUNDING.yml # 赞助配置
│ └── wiki/ # GitHub Wiki 内容
│
├── i18n/ # 多语言资产 (27 种语言)
│ ├── README.md # 多语言索引
│ ├── zh/ # 中文主语料
│ │ ├── documents/ # 文档库
│ │ │ ├── -01-哲学与方法论/ # 最高思想纲领与方法论
│ │ │ ├── 00-基础指南/ # 核心原则与底层逻辑
│ │ │ ├── 01-入门指南/ # 从零开始教程
│ │ │ ├── 02-方法论/ # 具体工具与技巧
│ │ │ ├── 03-实战/ # 项目实战案例
│ │ │ └── 04-资源/ # 外部资源聚合
│ │ ├── prompts/ # 提示词库
│ │ │ ├── 00-元提示词/ # 生成提示词的提示词
│ │ │ ├── 01-系统提示词/ # AI 系统级提示词
│ │ │ ├── 02-编程提示词/ # 编程相关提示词
│ │ │ └── 03-用户提示词/ # 用户自定义提示词
│ │ └── skills/ # 技能库
│ │ ├── 00-元技能/ # 生成技能的元技能
│ │ │ ├── claude-skills/ # 元技能核心
│ │ │ └── sop-generator/ # SOP 生成与规范化技能
│ │ ├── 01-AI工具/ # AI CLI 和工具
│ │ ├── 02-数据库/ # 数据库技能
│ │ ├── 03-加密货币/ # 加密货币/量化交易
│ │ └── 04-开发工具/ # 通用开发工具
│ ├── en/ # 英文版本（结构同 zh/）
│ └── ... # 其他语言骨架
├── documents/ # 文档库
│ ├── -01-哲学与方法论/ # 最高思想纲领与方法论
│ ├── 00-基础指南/ # 核心原则与底层逻辑
│ ├── 01-入门指南/ # 从零开始教程
│ ├── 02-方法论/ # 具体工具与技巧
│ ├── 03-实战/ # 项目实战案例
│ └── 04-资源/ # 外部资源聚合
│
├── prompts/ # 提示词库
│ ├── 00-元提示词/ # 生成提示词的提示词
│ ├── 01-系统提示词/ # AI 系统级提示词
│ ├── 02-编程提示词/ # 编程相关提示词
│ └── 03-用户提示词/ # 用户自定义提示词
│
├── skills/ # 技能库
│ ├── 00-元技能/ # 生成技能的元技能
│ ├── 01-AI工具/ # AI CLI 和工具
│ ├── 02-数据库/ # 数据库技能
│ ├── 03-加密货币/ # 加密货币/量化交易
│ ├── 04-开发工具/ # 通用开发工具
│ └── 05-生产力/ # 生产力工具
│
├── libs/ # 核心库代码
│ ├── common/ # 通用模块
@ -199,8 +194,8 @@ git push
- `AGENTS.md` - AI Agent 操作手册（本文件）
- `libs/external/prompts-library/main.py` - 提示词转换工具入口
- `backups/一键备份.sh` - 备份脚本入口
- `i18n/zh/skills/04-开发工具/tmux-autopilot/` - tmux 自动化操控技能（基于 oh-my-tmux，含 capture-pane/send-keys/蜂群巡检脚本）
- `i18n/zh/skills/00-元技能/sop-generator/` - SOP 生成与规范化技能（输入资料/需求 -> 标准 SOP）
- `skills/04-开发工具/tmux-autopilot/` - tmux 自动化操控技能（基于 oh-my-tmux，含 capture-pane/send-keys/蜂群巡检脚本）
- `skills/00-元技能/sop-generator/` - SOP 生成与规范化技能（输入资料/需求 -> 标准 SOP）
---
@ -283,9 +278,9 @@ bash backups/一键备份.sh
## Architecture & Structure
### Core Directories
- **`i18n/zh/prompts/`**: 核心提示词库（00-元提示词、01-系统提示词、02-编程提示词、03-用户提示词）
- **`i18n/zh/skills/`**: 模块化技能库（00-元技能、01-AI工具、02-数据库、03-加密货币、04-开发工具）
- **`i18n/zh/documents/`**: 知识库（-01-哲学与方法论、00-基础指南、01-入门指南、02-方法论、03-实战、04-资源）
- **`prompts/`**: 核心提示词库（00-元提示词、01-系统提示词、02-编程提示词、03-用户提示词）
- **`skills/`**: 模块化技能库（00-元技能、01-AI工具、02-数据库、03-加密货币、04-开发工具）
- **`documents/`**: 知识库（-01-哲学与方法论、00-基础指南、01-入门指南、02-方法论、03-实战、04-资源）
- **`libs/external/prompts-library/`**: Excel ↔ Markdown 转换工具
- **`libs/external/chat-vault/`**: AI 聊天记录保存工具
- **`backups/`**: 备份脚本与存档

100
README.md
View File

@ -10,7 +10,7 @@
<div align="center">
[中文](./README.md) | [English](./i18n/en/README.md)
[中文](./README.md)
# Vibe Coding 指南
@ -33,22 +33,22 @@
<!-- 资源直达 - 按重要性分组 -->
<!-- 🔴 核心理念 (红色系) -->
<p>
<a href="./i18n/zh/documents/-01-哲学与方法论/README.md"><img src="https://img.shields.io/badge/🔮_哲学方法论-底层协议-purple?style=for-the-badge" alt="哲学与方法论"></a>
<a href="./i18n/zh/documents/01-入门指南/00-Vibe%20Coding%20哲学原理.md"><img src="https://img.shields.io/badge/🧠_核心哲学-必读-crimson?style=for-the-badge" alt="核心哲学"></a>
<a href="./i18n/zh/documents/00-基础指南/胶水编程.md"><img src="https://img.shields.io/badge/🧬_胶水编程-银弹-red?style=for-the-badge" alt="胶水编程"></a>
<a href="./i18n/zh/documents/02-方法论/图形化AI协作-Canvas白板驱动开发.md"><img src="https://img.shields.io/badge/🎨_Canvas白板-图形驱动-orange?style=for-the-badge" alt="Canvas白板驱动开发"></a>
<a href="./i18n/zh/documents/01-入门指南/README.md"><img src="https://img.shields.io/badge/🚀_从零开始-新手入门-red?style=for-the-badge" alt="从零开始"></a>
<a href="./i18n/zh/documents/00-基础指南/血的教训.md"><img src="https://img.shields.io/badge/🩸_血的教训-必看-red?style=for-the-badge" alt="血的教训"></a>
<a href="./i18n/zh/documents/00-基础指南/语言层要素.md"><img src="https://img.shields.io/badge/📊_语言层要素-12层框架-gold?style=for-the-badge" alt="语言层要素"></a>
<a href="./i18n/zh/documents/00-基础指南/常见坑汇总.md"><img src="https://img.shields.io/badge/🕳️_常见坑-避坑指南-yellow?style=for-the-badge" alt="常见坑汇总"></a>
<a href="./i18n/zh/documents/00-基础指南/强前置条件约束.md"><img src="https://img.shields.io/badge/🚫_硬约束-铁律-darkred?style=for-the-badge" alt="强前置条件约束"></a>
<a href="./i18n/zh/documents/04-资源/外部资源聚合.md"><img src="https://img.shields.io/badge/📡_信息源-聚合-teal?style=for-the-badge" alt="信息源聚合"></a>
<a href="./i18n/zh/documents/00-基础指南/A%20Formalization%20of%20Recursive%20Self-Optimizing%20Generative%20Systems.md"><img src="https://img.shields.io/badge/📐_元方法论-递归优化-darkorange?style=for-the-badge" alt="元方法论"></a>
<a href="./i18n/zh/documents/00-基础指南/编程之道.md"><img src="https://img.shields.io/badge/🧭_编程之道-道法术-orange?style=for-the-badge" alt="编程之道"></a>
<a href="./i18n/zh/documents/03-实战/README.md"><img src="https://img.shields.io/badge/🎬_实战案例-项目实操-orange?style=for-the-badge" alt="实战案例"></a>
<a href="./i18n/zh/documents/04-资源/工具集.md"><img src="https://img.shields.io/badge/🛠️_工具集-速查-teal?style=for-the-badge" alt="工具集"></a>
<a href="./i18n/zh/prompts/"><img src="https://img.shields.io/badge/💬_提示词-精选-purple?style=for-the-badge" alt="提示词精选"></a>
<a href="./i18n/zh/skills/"><img src="https://img.shields.io/badge/⚡_Skills-技能大全-forestgreen?style=for-the-badge" alt="skills技能大全"></a>
<a href="./documents/-01-哲学与方法论/README.md"><img src="https://img.shields.io/badge/🔮_哲学方法论-底层协议-purple?style=for-the-badge" alt="哲学与方法论"></a>
<a href="./documents/01-入门指南/00-Vibe%20Coding%20哲学原理.md"><img src="https://img.shields.io/badge/🧠_核心哲学-必读-crimson?style=for-the-badge" alt="核心哲学"></a>
<a href="./documents/00-基础指南/胶水编程.md"><img src="https://img.shields.io/badge/🧬_胶水编程-银弹-red?style=for-the-badge" alt="胶水编程"></a>
<a href="./documents/02-方法论/图形化AI协作-Canvas白板驱动开发.md"><img src="https://img.shields.io/badge/🎨_Canvas白板-图形驱动-orange?style=for-the-badge" alt="Canvas白板驱动开发"></a>
<a href="./documents/01-入门指南/README.md"><img src="https://img.shields.io/badge/🚀_从零开始-新手入门-red?style=for-the-badge" alt="从零开始"></a>
<a href="./documents/00-基础指南/血的教训.md"><img src="https://img.shields.io/badge/🩸_血的教训-必看-red?style=for-the-badge" alt="血的教训"></a>
<a href="./documents/00-基础指南/语言层要素.md"><img src="https://img.shields.io/badge/📊_语言层要素-12层框架-gold?style=for-the-badge" alt="语言层要素"></a>
<a href="./documents/00-基础指南/常见坑汇总.md"><img src="https://img.shields.io/badge/🕳️_常见坑-避坑指南-yellow?style=for-the-badge" alt="常见坑汇总"></a>
<a href="./documents/00-基础指南/强前置条件约束.md"><img src="https://img.shields.io/badge/🚫_硬约束-铁律-darkred?style=for-the-badge" alt="强前置条件约束"></a>
<a href="./documents/04-资源/外部资源聚合.md"><img src="https://img.shields.io/badge/📡_信息源-聚合-teal?style=for-the-badge" alt="信息源聚合"></a>
<a href="./documents/00-基础指南/A%20Formalization%20of%20Recursive%20Self-Optimizing%20Generative%20Systems.md"><img src="https://img.shields.io/badge/📐_元方法论-递归优化-darkorange?style=for-the-badge" alt="元方法论"></a>
<a href="./documents/00-基础指南/编程之道.md"><img src="https://img.shields.io/badge/🧭_编程之道-道法术-orange?style=for-the-badge" alt="编程之道"></a>
<a href="./documents/03-实战/README.md"><img src="https://img.shields.io/badge/🎬_实战案例-项目实操-orange?style=for-the-badge" alt="实战案例"></a>
<a href="./documents/04-资源/工具集.md"><img src="https://img.shields.io/badge/🛠️_工具集-速查-teal?style=for-the-badge" alt="工具集"></a>
<a href="./prompts/"><img src="https://img.shields.io/badge/💬_提示词-精选-purple?style=for-the-badge" alt="提示词精选"></a>
<a href="./skills/"><img src="https://img.shields.io/badge/⚡_Skills-技能大全-forestgreen?style=for-the-badge" alt="skills技能大全"></a>
<a href="https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1254297203#gid=1254297203"><img src="https://img.shields.io/badge/📋_提示词-在线表格-blue?style=for-the-badge" alt="提示词在线表格"></a>
<a href="https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools"><img src="https://img.shields.io/badge/🔧_系统提示词-仓库-slateblue?style=for-the-badge" alt="系统提示词仓库"></a>
<a href="./libs/external/chat-vault/README_CN.md"><img src="https://img.shields.io/badge/🔐_Chat_Vault-AI会话库-gold?style=for-the-badge" alt="Chat Vault"></a>
@ -109,11 +109,11 @@
完全新手？按顺序完成以下步骤：
0. [00-Vibe Coding 哲学原理](./i18n/zh/documents/01-入门指南/00-Vibe%20Coding%20哲学原理.md) - 理解核心理念
1. [01-网络环境配置](./i18n/zh/documents/01-入门指南/01-网络环境配置.md) - 配置网络访问
2. [02-开发环境搭建](./i18n/zh/documents/01-入门指南/02-开发环境搭建.md) - 复制提示词给 AI，让 AI 指导你搭建环境
3. [03-IDE配置](./i18n/zh/documents/01-入门指南/03-IDE配置.md) - 配置 VS Code 编辑器
4. [04-OpenCode-CLI配置](./i18n/zh/documents/01-入门指南/04-OpenCode-CLI配置.md) - 免费 AI CLI 工具，支持 GLM-4.7/MiniMax M2.1 等模型
0. [00-Vibe Coding 哲学原理](./documents/01-入门指南/00-Vibe%20Coding%20哲学原理.md) - 理解核心理念
1. [01-网络环境配置](./documents/01-入门指南/01-网络环境配置.md) - 配置网络访问
2. [02-开发环境搭建](./documents/01-入门指南/02-开发环境搭建.md) - 复制提示词给 AI，让 AI 指导你搭建环境
3. [03-IDE配置](./documents/01-入门指南/03-IDE配置.md) - 配置 VS Code 编辑器
4. [04-OpenCode-CLI配置](./documents/01-入门指南/04-OpenCode-CLI配置.md) - 免费 AI CLI 工具，支持 GLM-4.7/MiniMax M2.1 等模型
---
@ -132,7 +132,7 @@
**核心理念**：能抄不写，能连不造，能复用不原创。
👉 [深入了解胶水编程](./i18n/zh/documents/00-基础指南/胶水编程.md)
👉 [深入了解胶水编程](./documents/00-基础指南/胶水编程.md)
</details>
@ -153,7 +153,7 @@ Canvas方式：**代码 ⇄ 白板 ⇄ AI ⇄ 人类**，白板成为单一真
**核心理念**：图形是第一公民，代码是白板的序列化形式。
👉 [深入了解Canvas白板驱动开发](./i18n/zh/documents/02-方法论/图形化AI协作-Canvas白板驱动开发.md)
👉 [深入了解Canvas白板驱动开发](./documents/02-方法论/图形化AI协作-Canvas白板驱动开发.md)
</details>
@ -174,7 +174,7 @@ Canvas方式：**代码 ⇄ 白板 ⇄ AI ⇄ 人类**，白板成为单一真
**核心突破**：AI 不再是孤立的，而是可以互相感知、通讯、控制的集群。
👉 [深入了解AI蜂群协作](./i18n/zh/documents/02-方法论/AI蜂群协作-tmux多Agent协作系统.md)
👉 [深入了解AI蜂群协作](./documents/02-方法论/AI蜂群协作-tmux多Agent协作系统.md)
</details>
@ -195,7 +195,7 @@ Canvas方式：**代码 ⇄ 白板 ⇄ AI ⇄ 人类**，白板成为单一真
**核心理念**：哲学不是空谈，是可落地的工程方法。
👉 [深入了解哲学方法论工具箱](./i18n/zh/documents/-01-哲学与方法论/README.md)
👉 [深入了解哲学方法论工具箱](./documents/-01-哲学与方法论/README.md)
</details>
@ -215,7 +215,7 @@ Canvas方式：**代码 ⇄ 白板 ⇄ AI ⇄ 人类**，白板成为单一真
该思想的核心是构建一个能够**自我优化**的 AI 系统。其递归本质可分解为以下步骤：
> 延伸阅读：[A Formalization of Recursive Self-Optimizing Generative Systems](./i18n/zh/documents/00-基础指南/A%20Formalization%20of%20Recursive%20Self-Optimizing%20Generative%20Systems.md)
> 延伸阅读：[A Formalization of Recursive Self-Optimizing Generative Systems](./documents/00-基础指南/A%20Formalization%20of%20Recursive%20Self-Optimizing%20Generative%20Systems.md)
#### 1. 定义核心角色：
@ -330,12 +330,12 @@ Canvas方式：**代码 ⇄ 白板 ⇄ AI ⇄ 人类**，白板成为单一真
* [**第三方系统提示词学习库**](https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools): 用于学习和参考其他 AI 工具的系统提示词。
* [**Skills 制作器**](https://github.com/yusufkaraaslan/Skill_Seekers): 可根据需求生成定制化 Skills 的工具。
* [**元提示词**](https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1254297203#gid=1254297203): 用于生成提示词的高级提示词。
* [**通用项目架构模板**](./i18n/zh/documents/00-基础指南/通用项目架构模板.md): 可用于快速搭建标准化的项目目录结构。
* [**元技能：Skills 的 Skills**](./i18n/zh/skills/00-元技能/claude-skills/SKILL.md): 用于生成 Skills 的元技能。
* [**SOP 生成 Skill**](./i18n/zh/skills/00-元技能/sop-generator/SKILL.md): 将资料/需求整理为可执行 SOP 的技能。
* [**tmux快捷键大全**](./i18n/zh/documents/02-方法论/tmux快捷键大全.md): tmux 的快捷键参考文档。
* [**LazyVim快捷键大全**](./i18n/zh/documents/02-方法论/LazyVim快捷键大全.md): LazyVim 的快捷键参考文档。
* [**手机远程 Vibe Coding**](./i18n/zh/documents/02-方法论/关于手机ssh任意位置链接本地计算机，基于frp实现的方法.md): 基于 frp 实现手机 SSH 远程控制本地电脑进行 Vibe Coding。
* [**通用项目架构模板**](./documents/00-基础指南/通用项目架构模板.md): 可用于快速搭建标准化的项目目录结构。
* [**元技能：Skills 的 Skills**](./skills/00-元技能/claude-skills/SKILL.md): 用于生成 Skills 的元技能。
* [**SOP 生成 Skill**](./skills/00-元技能/sop-generator/SKILL.md): 将资料/需求整理为可执行 SOP 的技能。
* [**tmux快捷键大全**](./documents/02-方法论/tmux快捷键大全.md): tmux 的快捷键参考文档。
* [**LazyVim快捷键大全**](./documents/02-方法论/LazyVim快捷键大全.md): LazyVim 的快捷键参考文档。
* [**手机远程 Vibe Coding**](./documents/02-方法论/关于手机ssh任意位置链接本地计算机，基于frp实现的方法.md): 基于 frp 实现手机 SSH 远程控制本地电脑进行 Vibe Coding。
### 外部教程与资源
@ -349,16 +349,16 @@ Canvas方式：**代码 ⇄ 白板 ⇄ AI ⇄ 人类**，白板成为单一真
### 项目内部文档
* [**胶水编程 (Glue Coding)**](./i18n/zh/documents/00-基础指南/): 软件工程的圣杯与银弹，Vibe Coding 的终极进化形态。
* [**胶水编程 (Glue Coding)**](./documents/00-基础指南/): 软件工程的圣杯与银弹，Vibe Coding 的终极进化形态。
* [**Chat Vault**](./libs/external/chat-vault/): AI 聊天记录保存工具，支持 Codex/Kiro/Gemini/Claude CLI。
* [**prompts-library 工具说明**](./libs/external/prompts-library/): 支持 Excel 与 Markdown 格式互转，包含数百个精选提示词。
* [**编程提示词集合**](./i18n/zh/prompts/02-编程提示词/): 适用于 Vibe Coding 流程的专用提示词。
* [**系统提示词构建原则**](./i18n/zh/documents/00-基础指南/系统提示词构建原则.md): 构建高效 AI 系统提示词的综合指南。
* [**开发经验总结**](./i18n/zh/documents/00-基础指南/开发经验.md): 变量命名、文件结构、编码规范、架构原则等。
* [**通用项目架构模板**](./i18n/zh/documents/00-基础指南/通用项目架构模板.md): 多种项目类型的标准目录结构。
* [**Augment MCP 配置文档**](./i18n/zh/documents/02-方法论/auggie-mcp配置文档.md): Augment 上下文引擎配置说明。
* [**系统提示词集合**](./i18n/zh/prompts/01-系统提示词/): AI 开发的系统提示词，含多版本开发规范。
* [**外部资源聚合**](./i18n/zh/documents/04-资源/外部资源聚合.md): GitHub 精选仓库、AI 工具平台、提示词资源、优质博主汇总。
* [**编程提示词集合**](./prompts/02-编程提示词/): 适用于 Vibe Coding 流程的专用提示词。
* [**系统提示词构建原则**](./documents/00-基础指南/系统提示词构建原则.md): 构建高效 AI 系统提示词的综合指南。
* [**开发经验总结**](./documents/00-基础指南/开发经验.md): 变量命名、文件结构、编码规范、架构原则等。
* [**通用项目架构模板**](./documents/00-基础指南/通用项目架构模板.md): 多种项目类型的标准目录结构。
* [**Augment MCP 配置文档**](./documents/02-方法论/auggie-mcp配置文档.md): Augment 上下文引擎配置说明。
* [**系统提示词集合**](./prompts/01-系统提示词/): AI 开发的系统提示词，含多版本开发规范。
* [**外部资源聚合**](./documents/04-资源/外部资源聚合.md): GitHub 精选仓库、AI 工具平台、提示词资源、优质博主汇总。
---
@ -406,7 +406,7 @@ Canvas方式：**代码 ⇄ 白板 ⇄ AI ⇄ 人类**，白板成为单一真
│ ├── FUNDING.yml # 赞助配置
│ └── wiki/ # GitHub Wiki 内容
│
├── i18n/ # 多语言资产 (27 种语言)
├── i18n/ # 多语言资产
│ ├── README.md # 多语言索引
│ ├── zh/ # 中文主语料
│ │ ├── documents/ # 文档库
@ -460,7 +460,7 @@ Canvas方式：**代码 ⇄ 白板 ⇄ AI ⇄ 人类**，白板成为单一真
一句话：Vibe Coding = **规划驱动 + 上下文固定 + AI 结对执行**，让「从想法到可维护代码」变成一条可审计的流水线，而不是一团无法迭代的巨石文件。
**你能得到**
- 成体系的提示词工具链：`i18n/zh/prompts/01-系统提示词/` 约束 AI 行为边界，`i18n/zh/prompts/02-编程提示词/` 提供需求澄清、计划、执行的全链路脚本。
- 成体系的提示词工具链：`prompts/01-系统提示词/` 约束 AI 行为边界，`prompts/02-编程提示词/` 提供需求澄清、计划、执行的全链路脚本。
- 闭环交付路径：需求 → 上下文文档 → 实施计划 → 分步实现 → 自测 → 进度记录，全程可复盘、可移交。
<details>
@ -470,12 +470,12 @@ Canvas方式：**代码 ⇄ 白板 ⇄ AI ⇄ 人类**，白板成为单一真
核心资产映射：
```
i18n/zh/prompts/
prompts/
00-元提示词/ # 用于生成提示词的高级提示词
01-系统提示词/ # 约束 AI 行为边界的系统级提示词
02-编程提示词/ # 需求澄清、计划、执行链的核心提示词
03-用户提示词/ # 可复用的用户侧提示词
i18n/zh/documents/
documents/
04-资源/代码组织.md, 04-资源/通用项目架构模板.md, 00-基础指南/开发经验.md, 00-基础指南/系统提示词构建原则.md 等知识库
backups/
一键备份.sh, 快速备份.py # 本地/远端快照脚本
@ -519,11 +519,11 @@ graph TB
end
subgraph consume_layer[执行与消费层]
artifacts_md --> catalog_coding[i18n/zh/prompts/02-编程提示词]
artifacts_md --> catalog_system[i18n/zh/prompts/01-系统提示词]
artifacts_md --> catalog_meta[i18n/zh/prompts/00-元提示词]
artifacts_md --> catalog_user[i18n/zh/prompts/03-用户提示词]
artifacts_md --> docs_repo[i18n/zh/documents/*]
artifacts_md --> catalog_coding[prompts/02-编程提示词]
artifacts_md --> catalog_system[prompts/01-系统提示词]
artifacts_md --> catalog_meta[prompts/00-元提示词]
artifacts_md --> catalog_user[prompts/03-用户提示词]
artifacts_md --> docs_repo[documents/*]
artifacts_md --> new_consumer[预留：其他下游渠道]
catalog_coding --> ai_flow[AI 结对编程流程]
ai_flow --> deliverables[项目上下文 / 计划 / 代码产出]

0
i18n/zh/documents/-01-哲学与方法论/AI蜂群协作.md → documents/-01-哲学与方法论/AI蜂群协作.md
View File

0
i18n/zh/documents/-01-哲学与方法论/README.md → documents/-01-哲学与方法论/README.md
View File

0
i18n/zh/documents/-01-哲学与方法论/现象学还原.md → documents/-01-哲学与方法论/现象学还原.md
View File

0
i18n/zh/documents/-01-哲学与方法论/辩证法.md → documents/-01-哲学与方法论/辩证法.md
View File

0
i18n/zh/documents/00-基础指南/A Formalization of Recursive Self-Optimizing Generative Systems.md → documents/00-基础指南/A Formalization of Recursive Self-Optimizing Generative Systems.md
View File

0
i18n/zh/documents/00-基础指南/README.md → documents/00-基础指南/README.md
View File

0
i18n/zh/documents/00-基础指南/代码组织.md → documents/00-基础指南/代码组织.md
View File

0
i18n/zh/documents/00-基础指南/审查代码.md → documents/00-基础指南/审查代码.md
View File

0
i18n/zh/documents/00-基础指南/常见坑汇总.md → documents/00-基础指南/常见坑汇总.md
View File

0
i18n/zh/documents/00-基础指南/开发经验.md → documents/00-基础指南/开发经验.md
View File

0
i18n/zh/documents/00-基础指南/强前置条件约束.md → documents/00-基础指南/强前置条件约束.md
View File

0
i18n/zh/documents/00-基础指南/系统提示词构建原则.md → documents/00-基础指南/系统提示词构建原则.md
View File

0
i18n/zh/documents/00-基础指南/编程之道.md → documents/00-基础指南/编程之道.md
View File

0
i18n/zh/documents/00-基础指南/胶水编程.md → documents/00-基础指南/胶水编程.md
View File

0
i18n/zh/documents/00-基础指南/血的教训.md → documents/00-基础指南/血的教训.md
View File

0
i18n/zh/documents/00-基础指南/语言层要素.md → documents/00-基础指南/语言层要素.md
View File

0
i18n/zh/documents/00-基础指南/通用项目架构模板.md → documents/00-基础指南/通用项目架构模板.md
View File

0
i18n/zh/documents/01-入门指南/00-Vibe Coding 哲学原理.md → documents/01-入门指南/00-Vibe Coding 哲学原理.md
View File

0
i18n/zh/documents/01-入门指南/01-网络环境配置.md → documents/01-入门指南/01-网络环境配置.md
View File

0
i18n/zh/documents/01-入门指南/02-开发环境搭建.md → documents/01-入门指南/02-开发环境搭建.md
View File

0
i18n/zh/documents/01-入门指南/03-IDE配置.md → documents/01-入门指南/03-IDE配置.md
View File

0
i18n/zh/documents/01-入门指南/04-OpenCode-CLI配置.md → documents/01-入门指南/04-OpenCode-CLI配置.md
View File

0
i18n/zh/documents/01-入门指南/README.md → documents/01-入门指南/README.md
View File

0
i18n/zh/documents/02-方法论/AI蜂群协作-tmux多Agent协作系统.md → documents/02-方法论/AI蜂群协作-tmux多Agent协作系统.md
View File

0
i18n/zh/documents/02-方法论/GEMINI-HEADLESS.md → documents/02-方法论/GEMINI-HEADLESS.md
View File

0
i18n/zh/documents/02-方法论/LazyVim快捷键大全.md → documents/02-方法论/LazyVim快捷键大全.md
View File

0
i18n/zh/documents/02-方法论/ProxyCast配置文档.md → documents/02-方法论/ProxyCast配置文档.md
View File

0
i18n/zh/documents/02-方法论/README.md → documents/02-方法论/README.md
View File

0
i18n/zh/documents/02-方法论/REMOTE_TUNNEL_GUIDE.md → documents/02-方法论/REMOTE_TUNNEL_GUIDE.md
View File

0
i18n/zh/documents/02-方法论/auggie-mcp配置文档.md → documents/02-方法论/auggie-mcp配置文档.md
View File

0
i18n/zh/documents/02-方法论/tmux快捷键大全.md → documents/02-方法论/tmux快捷键大全.md
View File

0
i18n/zh/documents/02-方法论/vibe-coding-经验收集.md → documents/02-方法论/vibe-coding-经验收集.md
View File

0
i18n/zh/documents/02-方法论/关于手机ssh任意位置链接本地计算机，基于frp实现的方法.md → documents/02-方法论/关于手机ssh任意位置链接本地计算机，基于frp实现的方法.md
View File

0
i18n/zh/documents/02-方法论/四阶段×十二原则方法论.md → documents/02-方法论/四阶段×十二原则方法论.md
View File

0
i18n/zh/documents/02-方法论/图形化AI协作-Canvas白板驱动开发.md → documents/02-方法论/图形化AI协作-Canvas白板驱动开发.md
View File

0
i18n/zh/documents/03-实战/README.md → documents/03-实战/README.md
View File

0
i18n/zh/documents/03-实战/fate-engine-dev/ascii可视化-prompt.md → documents/03-实战/fate-engine-dev/ascii可视化-prompt.md
View File

0
i18n/zh/documents/03-实战/fate-engine-dev/prompt-system-bazi-kline.md → documents/03-实战/fate-engine-dev/prompt-system-bazi-kline.md
View File

0
i18n/zh/documents/03-实战/fate-engine-dev/prompt-user-bazi-kline.md → documents/03-实战/fate-engine-dev/prompt-user-bazi-kline.md
View File

0
i18n/zh/documents/03-实战/fate-engine-dev/完整性检查-prompt.md → documents/03-实战/fate-engine-dev/完整性检查-prompt.md
View File

0
i18n/zh/documents/03-实战/fate-engine-dev/胶水开发要求-prompt.md → documents/03-实战/fate-engine-dev/胶水开发要求-prompt.md
View File

0
i18n/zh/documents/03-实战/fate-engine-dev/问题描述-prompt.md → documents/03-实战/fate-engine-dev/问题描述-prompt.md
View File

0
i18n/zh/documents/03-实战/polymarket-dev/POLYMARKET_LINK_FORMAT.md → documents/03-实战/polymarket-dev/POLYMARKET_LINK_FORMAT.md
View File

0
i18n/zh/documents/03-实战/polymarket-dev/Polymarket 套利全解析.md → documents/03-实战/polymarket-dev/Polymarket 套利全解析.md
View File

0
i18n/zh/documents/03-实战/polymarket-dev/README.md → documents/03-实战/polymarket-dev/README.md
View File

0
i18n/zh/documents/03-实战/polymarket-dev/ascii可视化-prompt.md → documents/03-实战/polymarket-dev/ascii可视化-prompt.md
View File

0
i18n/zh/documents/03-实战/polymarket-dev/复查-prompt.md → documents/03-实战/polymarket-dev/复查-prompt.md
View File

0
i18n/zh/documents/03-实战/polymarket-dev/完整性检查-prompt.md → documents/03-实战/polymarket-dev/完整性检查-prompt.md
View File

0
i18n/zh/documents/03-实战/polymarket-dev/胶水开发要求-prompt.md → documents/03-实战/polymarket-dev/胶水开发要求-prompt.md
View File

0
i18n/zh/documents/03-实战/polymarket-dev/问题描述-prompt.md → documents/03-实战/polymarket-dev/问题描述-prompt.md
View File

0
i18n/zh/documents/03-实战/telegram-dev/README.md → documents/03-实战/telegram-dev/README.md
View File

0
i18n/zh/documents/03-实战/telegram-dev/telegram Markdown 代码块格式修复记录 2025-12-15.md → documents/03-实战/telegram-dev/telegram Markdown 代码块格式修复记录 2025-12-15.md
View File

0
i18n/zh/documents/04-资源/README.md → documents/04-资源/README.md
View File

0
i18n/zh/documents/04-资源/外部资源聚合.md → documents/04-资源/外部资源聚合.md
View File

0
i18n/zh/documents/04-资源/工具集.md → documents/04-资源/工具集.md
View File

0
i18n/zh/documents/04-资源/编程书籍推荐.md → documents/04-资源/编程书籍推荐.md
View File

0
i18n/zh/documents/README.md → documents/README.md
View File

853
i18n/en/README.md
View File

@ -1,853 +0,0 @@
<!--
-------------------------------------------------------------------------------
Project Header Area (HEADER)
-------------------------------------------------------------------------------
-->
<p align="center">
<!-- Recommended size: 1280x640px. Can be created using tools like Canva, Figma or https://banners.beyondco.de/ -->
<img src="https://github.com/tukuaiai.png" alt="Vibe Coding Guide" width="50px">
</p>
<div align="center">
[中文](../../README.md) | [English](./README.md)
# Vibe Coding Guide
**The ultimate workstation for bringing ideas to life through AI pair programming**
---
<!--
Badges Area (BADGES)
-->
<!-- Project Status Badges -->
<p>
<a href="LICENSE"><img src="https://img.shields.io/github/license/tukuaiai/vibe-coding-cn?label=License&style=for-the-badge" alt="License"></a>
<a href="https://github.com/tukuaiai/vibe-coding-cn"><img src="https://img.shields.io/github/languages/top/tukuaiai/vibe-coding-cn?label=Language&style=for-the-badge" alt="Main Language"></a>
<a href="https://github.com/tukuaiai/vibe-coding-cn"><img src="https://img.shields.io/github/languages/code-size/tukuaiai/vibe-coding-cn?label=Code%20Size&style=for-the-badge" alt="Code Size"></a>
<a href="https://x.com/123olp"><img src="https://img.shields.io/badge/X-@123olp-black?style=for-the-badge&logo=x" alt="X"></a>
<a href="https://t.me/glue_coding"><img src="https://img.shields.io/badge/Chat-Telegram-blue?style=for-the-badge&logo=telegram" alt="Telegram Group"></a>
</p>
<!-- Resource Quick Links - Grouped by Importance -->
<!-- 🔴 Core Concepts (Red) -->
<p>
<a href="../zh/documents/-01-哲学与方法论/README.md"><img src="https://img.shields.io/badge/🔮_Philosophy_&_Methodology-Protocol-purple?style=for-the-badge" alt="Philosophy & Methodology"></a>
<a href="../zh/documents/01-入门指南/00-Vibe%20Coding%20哲学原理.md"><img src="https://img.shields.io/badge/🧠_Core_Philosophy-Must_Read-crimson?style=for-the-badge" alt="Core Philosophy"></a>
<a href="../zh/documents/00-基础指南/胶水编程.md"><img src="https://img.shields.io/badge/🧬_Glue_Coding-Silver_Bullet-red?style=for-the-badge" alt="Glue Coding"></a>
<a href="../zh/documents/02-方法论/图形化AI协作-Canvas白板驱动开发.md"><img src="https://img.shields.io/badge/🎨_Canvas_Whiteboard-Visual_Driven-orange?style=for-the-badge" alt="Canvas Whiteboard Driven Development"></a>
<a href="../zh/documents/01-入门指南/README.md"><img src="https://img.shields.io/badge/🚀_Getting_Started-Beginners-red?style=for-the-badge" alt="Getting Started"></a>
<a href="../zh/documents/00-基础指南/血的教训.md"><img src="https://img.shields.io/badge/🩸_Blood_Lessons-Must_See-red?style=for-the-badge" alt="Blood Lessons"></a>
<a href="../zh/documents/00-基础指南/语言层要素.md"><img src="https://img.shields.io/badge/📊_Language_Layers-12_Levels-gold?style=for-the-badge" alt="Language Layer Elements"></a>
<a href="../zh/documents/00-基础指南/常见坑汇总.md"><img src="https://img.shields.io/badge/🕳️_Common_Pitfalls-Guide-yellow?style=for-the-badge" alt="Common Pitfalls"></a>
<a href="../zh/documents/00-基础指南/强前置条件约束.md"><img src="https://img.shields.io/badge/🚫_Hard_Constraints-Iron_Laws-darkred?style=for-the-badge" alt="Hard Constraints"></a>
<a href="../zh/documents/04-资源/外部资源聚合.md"><img src="https://img.shields.io/badge/📡_Resources-Aggregation-teal?style=for-the-badge" alt="Resource Aggregation"></a>
<a href="../zh/documents/00-基础指南/A%20Formalization%20of%20Recursive%20Self-Optimizing%20Generative%20Systems.md"><img src="https://img.shields.io/badge/📐_Meta_Methodology-Recursive-darkorange?style=for-the-badge" alt="Meta Methodology"></a>
<a href="../zh/documents/00-基础指南/编程之道.md"><img src="https://img.shields.io/badge/🧭_Way_of_Programming-Dao_Fa_Shu-orange?style=for-the-badge" alt="Way of Programming"></a>
<a href="../zh/documents/03-实战/README.md"><img src="https://img.shields.io/badge/🎬_Practice-Projects-orange?style=for-the-badge" alt="Practice Projects"></a>
<a href="../zh/documents/04-资源/工具集.md"><img src="https://img.shields.io/badge/🛠️_Tools-Quick_Ref-teal?style=for-the-badge" alt="Tools"></a>
<a href="../zh/prompts/"><img src="https://img.shields.io/badge/💬_Prompts-Curated-purple?style=for-the-badge" alt="Curated Prompts"></a>
<a href="../zh/skills/"><img src="https://img.shields.io/badge/⚡_Skills-Collection-forestgreen?style=for-the-badge" alt="Skills Collection"></a>
<a href="https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1254297203#gid=1254297203"><img src="https://img.shields.io/badge/📋_Prompts-Online_Sheet-blue?style=for-the-badge" alt="Online Prompt Sheet"></a>
<a href="https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools"><img src="https://img.shields.io/badge/🔧_System_Prompts-Repo-slateblue?style=for-the-badge" alt="System Prompts Repo"></a>
<a href="../../libs/external/chat-vault/README_CN.md"><img src="https://img.shields.io/badge/🔐_Chat_Vault-AI_Sessions-gold?style=for-the-badge" alt="Chat Vault"></a>
</p>
[📋 Tools & Resources](#-the-tools-qi)
[🚀 Getting Started](#-getting-started)
[🎯 Original Repository Translation](#-original-repository-translation)
[⚙️ Full Setup Process](#️-full-setup-process)
[📞 Contact](#-contact)
[✨ Support Project](#-support-project)
[🤝 Contributing](#-contributing)
AI interpretation link for this repository: [zread.ai/tukuaiai/vibe-coding-cn](https://zread.ai/tukuaiai/vibe-coding-cn/1-overview)
</div>
## 🎲 Preface
**This is a constantly growing and self-negating project. All current experience and capabilities may become meaningless as AI evolves. So always maintain an AI-first mindset, don't be complacent, all experience may become obsolete - view it dialectically 🙏🙏🙏**
---
<details>
<summary><strong>⚡ 5-Minute Quick Start</strong></summary>
## ⚡ 5-Minute Quick Start
> Already have network and development environment? Start Vibe Coding directly!
**Step 1**: Copy the prompt below and paste it into [Claude](https://claude.ai/) or [ChatGPT](https://chatgpt.com/)
```
You are a professional AI programming assistant. I want to develop a project using the Vibe Coding approach.
Please ask me first:
1. What project do you want to build? (one sentence description)
2. What programming languages are you familiar with? (it's okay if you're not familiar with any)
3. What is your operating system?
Then help me:
1. Recommend the simplest tech stack
2. Generate project structure
3. Guide me step by step to complete development
Requirement: After completing each step, ask me if it was successful before continuing to the next step.
```
**Step 2**: Follow AI's guidance to turn your ideas into reality 🚀
**That's it!** Read on for more advanced content 👇
</details>
---
## 🚀 Getting Started
Complete beginner? Follow these steps in order:
0. [00-Vibe Coding Philosophy](../zh/documents/01-入门指南/00-Vibe%20Coding%20哲学原理.md) - Understand core concepts
1. [01-Network Environment Configuration](../zh/documents/01-入门指南/01-网络环境配置.md) - Configure network access
2. [02-Development Environment Setup](../zh/documents/01-入门指南/02-开发环境搭建.md) - Copy prompts to AI, let AI guide you through environment setup
3. [03-IDE Configuration](../zh/documents/01-入门指南/03-IDE配置.md) - Configure VS Code editor
4. [04-OpenCode-CLI Configuration](../zh/documents/01-入门指南/04-OpenCode-CLI配置.md) - Free AI CLI tool, supports GLM-4.7/MiniMax M2.1 and other models
---
<details open>
<summary><strong>🧬 Glue Coding</strong></summary>
> **The Holy Grail and Silver Bullet of Software Engineering**
Glue Coding is the ultimate evolution of Vibe Coding, potentially solving three fatal flaws:
| Problem | Solution |
|:---|:---|
| 🎭 AI Hallucination | ✅ Only use verified mature code, zero hallucination |
| 🧩 Complexity Explosion | ✅ Every module is a battle-tested wheel |
| 🎓 High Barrier | ✅ You only need to describe "how to connect" |
**Core Philosophy**: Copy instead of write, connect instead of create, reuse instead of reinvent.
👉 [Learn more about Glue Coding](../zh/documents/00-基础指南/胶水编程.md)
</details>
<details open>
<summary><strong>🎨 Canvas Whiteboard-Driven Development</strong></summary>
> **A New Paradigm for Visual AI Collaboration**
Traditional development: Code → Verbal communication → Mental architecture → Code out of control
Canvas approach: **Code ⇄ Whiteboard ⇄ AI ⇄ Human**, whiteboard becomes the single source of truth
| Pain Point | Solution |
|:---|:---|
| 🤖 AI can't understand project structure | ✅ AI directly reads whiteboard JSON, instantly understands architecture |
| 🧠 Humans can't remember complex dependencies | ✅ Clear connections, one glance shows all impacts |
| 💬 Team collaboration relies on verbal communication | ✅ Point at the whiteboard to explain, newcomers understand in 5 minutes |
**Core Philosophy**: Graphics are first-class citizens, code is the serialized form of the whiteboard.
👉 [Learn more about Canvas Whiteboard-Driven Development](../zh/documents/02-方法论/图形化AI协作-Canvas白板驱动开发.md)
</details>
<details open>
<summary><strong>🐝 AI Swarm Collaboration</strong></summary>
> **Multi-AI Agent Collaboration System Based on tmux**
Traditional mode: Human ←→ AI₁, Human ←→ AI₂, Human ←→ AI₃ (Human is the bottleneck)
Swarm mode: **Human → AI₁ ←→ AI₂ ←→ AI₃** (AI autonomous collaboration)
| Capability | Implementation | Effect |
|:---|:---|:---|
| 🔍 Perception | `capture-pane` | Read any terminal content |
| 🎮 Control | `send-keys` | Send keystrokes to any terminal |
| 🤝 Coordination | Shared state files | Task synchronization and division |
**Core Breakthrough**: AI is no longer isolated, but a cluster that can perceive, communicate, and control each other.
👉 [Learn more about AI Swarm Collaboration](../zh/documents/02-方法论/AI蜂群协作-tmux多Agent协作系统.md)
</details>
<details open>
<summary><strong>🔮 Philosophy & Methodology Toolbox</strong></summary>
> **Systematize Vibe into verifiable, iterable, and convergent engineering output**
23 philosophical methodologies + Python tools + copy-paste prompts, covering:
| Method | Use Case |
|:---|:---|
| Phenomenological Reduction | When requirements are vague, clear assumptions and return to observable facts |
| Thesis-Antithesis-Synthesis | Rapid prototype → Counter-examples → Converge to engineering version |
| Falsificationism | Use tests to reveal failure modes |
| Occam's Razor | Remove unnecessary complexity |
| Bayesian Update | Dynamically adjust beliefs based on new evidence |
**Core Philosophy**: Philosophy is not empty talk, it's actionable engineering methodology.
👉 [Learn more about Philosophy & Methodology Toolbox](../zh/documents/-01-哲学与方法论/README.md)
</details>
---
## 🖼️ Overview
**Vibe Coding** is the ultimate workflow for AI pair programming, designed to help developers smoothly bring ideas to life. This guide details the entire process from project conception, technology selection, implementation planning to specific development, debugging, and expansion. It emphasizes **planning-driven** and **modularization** as the core, preventing AI from going out of control and leading to project chaos.
> **Core Philosophy**: *Planning is everything.* Be cautious about letting AI autonomously plan, otherwise your codebase will become an unmanageable mess.
**Note**: The following experience sharing is not universally applicable. Please adopt it dialectically in specific practices combined with your scenario.
<details open>
<summary><strong>🔑 Meta-Methodology</strong></summary>
The core of this philosophy is to build an AI system capable of **self-optimization**. Its recursive nature can be broken down into the following steps:
> Further reading: [A Formalization of Recursive Self-Optimizing Generative Systems](../zh/documents/00-基础指南/A%20Formalization%20of%20Recursive%20Self-Optimizing%20Generative%20Systems.md)
#### 1. Define Core Roles:
* **α-Prompt (Generator)**: A "parent" prompt whose sole responsibility is to **generate** other prompts or skills.
* **Ω-Prompt (Optimizer)**: Another "parent" prompt whose sole responsibility is to **optimize** other prompts or skills.
#### 2. Describe the Recursive Lifecycle:
1. **Bootstrap**:
* Use AI to generate initial versions (v1) of `α-Prompt` and `Ω-Prompt`.
2. **Self-Correction & Evolution**:
* Use `Ω-Prompt (v1)` to **optimize** `α-Prompt (v1)`, thereby obtaining a more powerful `α-Prompt (v2)`.
3. **Generation**:
* Use the **evolved** `α-Prompt (v2)` to generate all required target prompts and skills.
4. **Recursive Loop**:
* Feed the newly generated, more powerful products (including new versions of `Ω-Prompt`) back into the system, again for optimizing `α-Prompt`, thereby initiating continuous evolution.
#### 3. Ultimate Goal:
Through this continuous **recursive optimization loop**, the system achieves **self-transcendence** in each iteration, infinitely approaching the preset **expected state**.
</details>
<details open>
<summary><strong>🧭 Methodology Essence (Dao · Fa · Shu)</strong></summary>
## 🧭 The Way (Dao)
* **If AI can do it, don't do it manually**
* **Ask AI everything**
* **Purpose-driven: All actions in the development process revolve around "purpose"**
* **Context is the primary element of Vibe Coding; garbage in, garbage out**
* **Systemic thinking: entities, links, functions/purposes, three dimensions**
* **Data and functions are everything in programming**
* **Input, process, output describe the entire process**
* **Frequently ask AI: What is it? Why? How to do it? (Golden Circle Rule)**
* **Structure first, then code; always plan the framework well, otherwise technical debt will be endless**
* **Occam's Razor: Do not add code if unnecessary**
* **Pareto Principle: Focus on the important 20%**
* **Reverse thinking: First clarify your requirements, then build code reversely from requirements**
* **Repeat, try multiple times, if it really doesn't work, open a new window**
* **Focus, extreme focus can penetrate code; do one thing at a time (except for divine beings)**
## 🧩 The Method (Fa)
* **One-sentence goal + non-goals**
* **Orthogonality (scenario-dependent)**
* **Copy, don't write: don't reinvent the wheel, first ask AI if there's a suitable repository, download and modify it (glue coding new paradigm)**
* **Always read the official documentation; first crawl the official documentation and feed it to AI (let AI find tools to download locally)**
* **Split modules by responsibility**
* **Interfaces first, implementation later**
* **Change only one module at a time**
* **Documentation is context, not an afterthought**
## 🛠️ The Techniques (Shu)
* Clearly state: **What can be changed, what cannot be changed**
* Debug only provide: **Expected vs. Actual + Minimum Reproduction**
* Testing can be handed over to AI, **assertions human-reviewed**
* Too much code, **switch sessions**
* **AI mistakes should be organized into experience using prompts for persistent storage; when encountering unsolvable problems, let AI search this collected issues and find solutions**
</details>
<details open>
<summary><strong>📋 The Tools (Qi)</strong></summary>
## 📋 The Tools (Qi)
### Integrated Development Environment (IDE) & Terminal
* [**Visual Studio Code**](https://code.visualstudio.com/): A powerful integrated development environment, suitable for code reading and manual modifications. Its `Local History` plugin is particularly convenient for project version management.
* **Virtual Environment (.venv)**: Highly recommended for one-click configuration and isolation of project environments, especially for Python development.
* [**Cursor**](https://cursor.com/): Has already captured user mindshare and is widely known.
* [**Warp**](https://www.warp.dev/): A modern terminal integrated with AI features, effectively improving command-line operations and error troubleshooting efficiency.
* [**Neovim (nvim)**](https://github.com/neovim/neovim): A high-performance modern Vim editor with a rich plugin ecosystem, the first choice for keyboard-driven developers.
* [**LazyVim**](https://github.com/LazyVim/LazyVim): A configuration framework based on Neovim, pre-configured with LSP, code completion, debugging, and other full-featured functionalities, achieving a balance between out-of-the-box usability and deep customization.
### AI Models & Services
* [**Claude Opus 4.6**](https://claude.ai/new): A powerful AI model, offered through platforms like Claude Code, and supporting CLI and IDE plugins.
* [**gpt-5.3-codex (xhigh)**](https://chatgpt.com/codex/): An AI model suitable for handling large projects and complex logic, usable through platforms like Codex CLI.
* [**Droid**](https://factory.ai/news/terminal-bench): Provides CLI access to various models including Claude Opus 4.6.
* [**Kiro**](https://kiro.dev/): Currently offers free access to the Claude Opus 4.6 model, and provides client and CLI tools.
* [**Gemini CLI**](https://geminicli.com/): Provides free access to the Gemini model, suitable for executing scripts, organizing documents, and exploring ideas.
* [**antigravity**](https://antigravity.google/): Currently a free AI service provided by Google, supporting Claude Opus 4.6 and Gemini 3.0 Pro.
* [**AI Studio**](https://aistudio.google.com/prompts/new_chat): A free service provided by Google, supporting Gemini 3.0 Pro and Nano Banana.
* [**Gemini Enterprise**](https://cloud.google.com/gemini-enterprise): Google's AI service for enterprise users, currently available for free.
* [**GitHub Copilot**](https://github.com/copilot): An AI code completion tool jointly developed by GitHub and OpenAI.
* [**Kimi K2.5**](https://www.kimi.com/): A domestic AI model suitable for various general tasks.
* [**GLM**](https://bigmodel.cn/): A domestic large language model developed by Zhipu AI.
* [**Qwen**](https://qwenlm.github.io/qwen-code-docs/zh/cli/): An AI model developed by Alibaba, its CLI tool offers free usage quota.
### Development and Auxiliary Tools
* [**Augment**](https://app.augmentcode.com/): Provides powerful context engine and prompt optimization features.
* [**Windsurf**](https://windsurf.com/): An AI development tool offering free credits to new users.
* [**Ollama**](https://ollama.com/): A local large model management tool that allows easy pulling and running of open-source models via the command line.
* [**Mermaid Chart**](https://www.mermaidchart.com/): Used to convert text descriptions into visual diagrams like architecture diagrams and sequence diagrams.
* [**NotebookLM**](https://notebooklm.google.com/): A tool for AI interpretation of materials, audio, and generating mind maps.
* [**Zread**](https://zread.ai/): An AI-driven GitHub repository reading tool that helps quickly understand project code.
* [**tmux**](https://github.com/tmux/tmux): A powerful terminal multiplexer that supports session persistence, splitting panes, and background tasks, ideal for server and multi-project development.
* [**DBeaver**](https://dbeaver.io/): A universal database management client that supports various databases and offers comprehensive features.
### Resources and Templates
* [**Prompt Library (Online Table)**](https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1254297203#gid=1254297203): An online table containing a large number of ready-to-use prompts for various categories.
* [**Third-party System Prompt Learning Library**](https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools): For learning and referencing system prompts of other AI tools.
* [**Skills Maker**](https://github.com/yusufkaraaslan/Skill_Seekers): A tool for generating customized skills based on requirements.
* [**Meta-Prompts**](https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1254297203#gid=1254297203): Advanced prompts for generating prompts.
* [**General Project Architecture Template**](../zh/documents/00-基础指南/通用项目架构模板.md): Can be used to quickly set up standardized project directory structures.
* [**Meta-Skill: Skills of Skills**](../zh/skills/00-元技能/claude-skills/SKILL.md): A meta-skill for generating skills.
* [**tmux Shortcut Cheatsheet**](../zh/documents/02-方法论/tmux快捷键大全.md): Reference documentation for tmux shortcuts.
* [**LazyVim Shortcut Cheatsheet**](../zh/documents/02-方法论/LazyVim快捷键大全.md): Reference documentation for LazyVim shortcuts.
* [**Mobile Remote Vibe Coding**](../zh/documents/02-方法论/关于手机ssh任意位置链接本地计算机，基于frp实现的方法.md): SSH remote control of local computer via mobile phone for Vibe Coding based on frp.
### External Tutorials and Resources
* [**Erge's Java Advanced Path**](https://javabetter.cn/): Contains detailed configuration tutorials for various development tools.
* [**Virtual Card**](https://www.bybit.com/cards/?ref=YDGAVPN&source=applet_invite): Can be used for registering cloud services and other scenarios requiring international payments.
### Community
* [**Telegram Group**](https://t.me/glue_coding): Vibe Coding Chinese exchange group
* [**Telegram Channel**](https://t.me/tradecat_ai_channel): Project updates and news
### Internal Project Documentation
* [**Glue Coding**](../zh/documents/00-基础指南/): The Holy Grail and Silver Bullet of software engineering, the ultimate evolution of Vibe Coding.
* [**Chat Vault**](../../libs/external/chat-vault/): AI chat record saving tool, supporting Codex/Kiro/Gemini/Claude CLI.
* [**prompts-library Tool Description**](../../libs/external/prompts-library/): Supports mutual conversion between Excel and Markdown formats, contains hundreds of curated prompts.
* [**Coding Prompts Collection**](../zh/prompts/02-编程提示词/): Dedicated prompts for the Vibe Coding process.
* [**System Prompt Construction Principles**](../zh/documents/00-基础指南/系统提示词构建原则.md): A comprehensive guide on building efficient AI system prompts.
* [**Development Experience Summary**](../zh/documents/00-基础指南/开发经验.md): Variable naming, file structure, coding standards, architectural principles, etc.
* [**General Project Architecture Template**](../zh/documents/00-基础指南/通用项目架构模板.md): Standard directory structures for various project types.
* [**Augment MCP Configuration Document**](../zh/documents/02-方法论/auggie-mcp配置文档.md): Augment context engine configuration instructions.
* [**System Prompts Collection**](../zh/prompts/01-系统提示词/): System prompts for AI development, including multiple versions of development specifications.
* [**External Resource Aggregation**](../zh/documents/04-资源/外部资源聚合.md): GitHub curated repositories, AI tool platforms, prompt resources, quality bloggers compilation.
---
</details>
<details open>
<summary><strong>Coding Model Performance Tier Reference</strong></summary>
## Coding Model Performance Tier Reference
It is recommended to only choose models from the first tier for complex tasks to ensure optimal results and efficiency.
* **Tier 1**: `codex-5.1-max-xhigh`, `claude-opus-4.5-xhigh`, `gpt-5.2-xhigh`
---
</details>
<details>
<summary><strong>Project Directory Structure Overview</strong></summary>
### Project Directory Structure Overview
The core structure of this `vibe-coding-cn` project primarily revolves around knowledge management and the organization and automation of AI prompts. Below is a reorganized and simplified directory tree with explanations for each part:
```
.
├── README.md # Main project documentation
├── AGENTS.md # AI Agent behavioral guidelines
├── GEMINI.md # Gemini model context
├── Makefile # Automation scripts
├── LICENSE # MIT License
├── CODE_OF_CONDUCT.md # Code of Conduct
├── CONTRIBUTING.md # Contribution Guide
├── .gitignore # Git ignore rules
│
├── .github/ # GitHub configuration
│ ├── workflows/ # CI/CD workflows
│ │ ├── ci.yml # Markdown lint + link checker
│ │ ├── labeler.yml # Auto labeler
│ │ └── welcome.yml # Welcome new contributors
│ ├── ISSUE_TEMPLATE/ # Issue templates
│ ├── PULL_REQUEST_TEMPLATE.md # PR template
│ ├── SECURITY.md # Security policy
│ ├── FUNDING.yml # Sponsorship configuration
│ └── wiki/ # GitHub Wiki content
│
├── i18n/ # Multilingual assets (27 languages)
│ ├── README.md # Multilingual index
│ ├── zh/ # Chinese main corpus
│ │ ├── documents/ # Document library
│ │ │ ├── -01-哲学与方法论/ # Supreme ideology and methodology
│ │ │ ├── 00-基础指南/ # Core principles and underlying logic
│ │ │ ├── 01-入门指南/ # Getting started tutorials
│ │ │ ├── 02-方法论/ # Specific tools and techniques
│ │ │ ├── 03-实战/ # Project practice cases
│ │ │ └── 04-资源/ # External resource aggregation
│ │ ├── prompts/ # Prompt library
│ │ │ ├── 00-元提示词/ # Meta prompts (prompts that generate prompts)
│ │ │ ├── 01-系统提示词/ # AI system-level prompts
│ │ │ ├── 02-编程提示词/ # Programming-related prompts
│ │ │ └── 03-用户提示词/ # User-defined prompts
│ │ └── skills/ # Skills library
│ │ ├── 00-元技能/ # Meta skills (skills that generate skills)
│ │ ├── 01-AI工具/ # AI CLI and tools
│ │ ├── 02-数据库/ # Database skills
│ │ ├── 03-加密货币/ # Cryptocurrency/quantitative trading
│ │ └── 04-开发工具/ # General development tools
│ ├── en/ # English version (same structure as zh/)
│ └── ... # Other language skeletons
│
├── libs/ # Core library code
│ ├── common/ # Common modules
│ │ ├── models/ # Model definitions
│ │ └── utils/ # Utility functions
│ ├── database/ # Database module (reserved)
│ └── external/ # External tools
│ ├── prompts-library/ # Excel ↔ Markdown conversion tool
│ ├── chat-vault/ # AI chat record saving tool
│ ├── Skill_Seekers-development/ # Skills maker
│ ├── l10n-tool/ # Multilingual translation script
│ ├── my-nvim/ # Neovim configuration
│ ├── MCPlayerTransfer/ # MC player migration tool
│ └── XHS-image-to-PDF-conversion/ # Xiaohongshu image to PDF
│
└── backups/ # Backup scripts and archives
├── 一键备份.sh # Shell backup script
├── 快速备份.py # Python backup script
├── README.md # Backup instructions
└── gz/ # Compressed archive directory
```
---
</details>
## 📺 Demo and Output
In one sentence: Vibe Coding = **Planning-driven + Context-fixed + AI Pair Execution**, transforming "idea to maintainable code" into an auditable pipeline, rather than an uniteratable monolith.
**What you will get**
- A systematic prompt toolchain: `i18n/zh/prompts/01-系统提示词/` defines AI behavioral boundaries, `i18n/zh/prompts/02-编程提示词/` provides full-link scripts for demand clarification, planning, and execution.
- Closed-loop delivery path: Requirement → Context document → Implementation plan → Step-by-step implementation → Self-testing → Progress recording, fully reviewable and transferable.
<details>
<summary><strong>⚙️ Architecture and Workflow</strong></summary>
## ⚙️ Architecture and Workflow
Core Asset Mapping:
```
i18n/zh/prompts/
00-元提示词/ # Advanced prompts for generating prompts
01-系统提示词/ # System-level prompts constraining AI behavior
02-编程提示词/ # Core prompts for demand clarification, planning, and execution
03-用户提示词/ # Reusable user-side prompts
i18n/zh/documents/
04-资源/代码组织.md, 04-资源/通用项目架构模板.md, 00-基础指南/开发经验.md, 00-基础指南/系统提示词构建原则.md and other knowledge bases
backups/
一键备份.sh, 快速备份.py # Local/remote snapshot scripts
```
```mermaid
graph TB
%% GitHub compatible simplified version (using only basic syntax)
subgraph ext_layer[External Systems and Data Sources Layer]
ext_contrib[Community Contributors]
ext_sheet[Google Sheets / External Tables]
ext_md[External Markdown Prompts]
ext_api[Reserved: Other Data Sources / APIs]
ext_contrib --> ext_sheet
ext_contrib --> ext_md
ext_api --> ext_sheet
end
subgraph ingest_layer[Data Ingestion and Collection Layer]
excel_raw[prompt_excel/*.xlsx]
md_raw[prompt_docs/External MD Input]
excel_to_docs[prompts-library/scripts/excel_to_docs.py]
docs_to_excel[prompts-library/scripts/docs_to_excel.py]
ingest_bus[Standardized Data Frame]
ext_sheet --> excel_raw
ext_md --> md_raw
excel_raw --> excel_to_docs
md_raw --> docs_to_excel
excel_to_docs --> ingest_bus
docs_to_excel --> ingest_bus
end
subgraph core_layer[Data Processing and Intelligent Decision Layer / Core]
ingest_bus --> validate[Field Validation and Normalization]
validate --> transform[Format Mapping Transformation]
transform --> artifacts_md[prompt_docs/Standardized MD]
transform --> artifacts_xlsx[prompt_excel/Export XLSX]
orchestrator[main.py · scripts/start_convert.py] --> validate
orchestrator --> transform
end
subgraph consume_layer[Execution and Consumption Layer]
artifacts_md --> catalog_coding[i18n/zh/prompts/02-编程提示词]
artifacts_md --> catalog_system[i18n/zh/prompts/01-系统提示词]
artifacts_md --> catalog_meta[i18n/zh/prompts/00-元提示词]
artifacts_md --> catalog_user[i18n/zh/prompts/03-用户提示词]
artifacts_md --> docs_repo[i18n/zh/documents/*]
artifacts_md --> new_consumer[Reserved: Other Downstream Channels]
catalog_coding --> ai_flow[AI Pair Programming Workflow]
ai_flow --> deliverables[Project Context / Plan / Code Output]
end
subgraph ux_layer[User Interaction and Interface Layer]
cli[CLI: python main.py] --> orchestrator
makefile[Makefile Task Encapsulation] --> cli
readme[README.md Usage Guide] --> cli
end
subgraph infra_layer[Infrastructure and Cross-cutting Capabilities Layer]
git[Git Version Control] --> orchestrator
backups[backups/一键备份.sh · backups/快速备份.py] --> artifacts_md
deps[requirements.txt · scripts/requirements.txt] --> orchestrator
config[prompts-library/scripts/config.yaml] --> orchestrator
monitor[Reserved: Logging and Monitoring] --> orchestrator
end
```
---
</details>
<details>
<summary>📈 Performance Benchmarks (Optional)</summary>
This repository is positioned as a "workflow and prompts" library rather than a performance-oriented codebase. It is recommended to track the following observable metrics (currently primarily relying on manual recording, which can be scored/marked in `progress.md`):
| Metric | Meaning | Current Status/Suggestion |
|:---|:---|:---|
| Prompt Hit Rate | Proportion of generations that meet acceptance criteria on the first try | To be recorded; mark 0/1 after each task in progress.md |
| Turnaround Time | Time required from requirement to first runnable version | Mark timestamps during screen recording, or use CLI timer to track |
| Change Reproducibility | Whether context/progress/backup is updated synchronously | Manual update; add git tags/snapshots to backup scripts |
| Routine Coverage | Presence of minimum runnable examples/tests | Recommend keeping README + test cases for each example project |
</details>
---
## 🗺️ Roadmap
```mermaid
gantt
title Project Development Roadmap
dateFormat YYYY-MM
section In Progress (2025 Q4)
Complete demo GIFs and example projects: active, 2025-12, 30d
External resource aggregation completion: active, 2025-12, 20d
section Near Term (2026 Q1)
Prompt index auto-generation script: 2026-01, 15d
One-click demo/verification CLI workflow: 2026-01, 15d
Backup script adds snapshot and validation: 2026-02, 10d
section Mid Term (2026 Q2)
Templated example project set: 2026-03, 30d
Multi-model comparison and evaluation baseline: 2026-04, 30d
```
---
## 🎯 Original Repository Translation
> The following content is translated from the original repository [EnzeD/vibe-coding](https://github.com/EnzeD/vibe-coding)
To start Vibe Coding, you only need one of the following two tools:
- **Claude Opus 4.6**, used in Claude Code
- **gpt-5.3-codex (xhigh)**, used in Codex CLI
This guide applies to both the CLI terminal version and the VSCode extension version (both Codex and Claude Code have extensions, and their interfaces are updated).
*(Note: Earlier versions of this guide used **Grok 3**, later switched to **Gemini 2.5 Pro**, and now we are using **Claude 4.6** (or **gpt-5.3-codex (xhigh)**))*
*(Note 2: If you want to use Cursor, please check version [1.1](https://github.com/EnzeD/vibe-coding/tree/1.1.1) of this guide, but we believe it is currently less powerful than Codex CLI or Claude Code)*
---
<details>
<summary><strong>⚙️ Full Setup Process</strong></summary>
<details>
<summary><strong>1. Game Design Document</strong></summary>
- Hand your game idea to **gpt-5.3-codex** or **Claude Opus 4.6** to generate a concise **Game Design Document** in Markdown format, named `game-design-document.md`.
- Review and refine it yourself to ensure it aligns with your vision. It can be very basic initially; the goal is to provide AI with the game structure and intent context. Do not over-design; it will be iterated later.
</details>
<details>
<summary><strong>2. Tech Stack and <code>CLAUDE.md</code> / <code>Agents.md</code></strong></summary>
- Ask **gpt-5.3-codex** or **Claude Opus 4.6** to recommend the most suitable tech stack for your game (e.g., ThreeJS + WebSocket for a multiplayer 3D game), save it as `tech-stack.md`.
- Ask it to propose the **simplest yet most robust** tech stack.
- Open **Claude Code** or **Codex CLI** in your terminal and use the `/init` command. It will read the two `.md` files you've created and generate a set of rules to guide the large model correctly.
- **Key: Always review the generated rules.** Ensure the rules emphasize **modularization** (multiple files) and prohibit **monolithic files**. You may need to manually modify or supplement the rules.
- **Extremely Important:** Some rules must be set to **"Always"** to force AI to read them before generating any code. For example, add the following rules and mark them as "Always":
> ```
> # Important Note:
> # Before writing any code, you must fully read memory-bank/@architecture.md (including full database structure).
> # Before writing any code, you must fully read memory-bank/@game-design-document.md.
> # After completing a major feature or milestone, you must update memory-bank/@architecture.md.
> ```
- Other (non-Always) rules should guide AI to follow best practices for your tech stack (e.g., networking, state management).
- *If you want the cleanest code and most optimized project, this entire set of rule settings is mandatory.*
</details>
<details>
<summary><strong>3. Implementation Plan</strong></summary>
- Provide the following to **gpt-5.3-codex** or **Claude Opus 4.6**:
- Game Design Document (`game-design-document.md`)
- Tech Stack Recommendation (`tech-stack.md`)
- Ask it to generate a detailed **Implementation Plan** (Markdown format), containing a series of step-by-step instructions for AI developers.
- Each step should be small and specific.
- Each step must include tests to verify correctness.
- Strictly no code - only write clear, specific instructions.
- Focus on the **basic game** first; full features will be added later.
</details>
<details>
<summary><strong>4. Memory Bank</strong></summary>
- Create a new project folder and open it in VSCode.
- Create a subfolder `memory-bank` in the project root.
- Place the following files into `memory-bank`:
- `game-design-document.md`
- `tech-stack.md`
- `implementation-plan.md`
- `progress.md` (create an empty file to record completed steps)
- `architecture.md` (create an empty file to record the purpose of each file)
</details>
</details>
<details>
<summary><strong>🎮 Vibe Coding Develops the Basic Game</strong></summary>
Now for the most exciting part!
<details>
<summary><strong>Ensure Everything is Clear</strong></summary>
- Open **Codex** or **Claude Code** in the VSCode extension, or launch Claude Code / Codex CLI in the project terminal.
- Prompt: Read all documents in `/memory-bank`. Is `implementation-plan.md` completely clear? What questions do you have for me to clarify, so that it is 100% clear to you?
- It will usually ask 9-10 questions. After answering all of them, ask it to modify `implementation-plan.md` based on your answers to make the plan more complete.
</details>
<details>
<summary><strong>Your First Implementation Prompt</strong></summary>
- Open **Codex** or **Claude Code** (extension or terminal).
- Prompt: Read all documents in `/memory-bank`, then execute step 1 of the implementation plan. I will be responsible for running tests. Do not start step 2 until I verify the tests pass. After verification, open `progress.md` to record what you've done for future developers' reference, and add new architectural insights to `architecture.md` explaining the purpose of each file.
- **Always** use "Ask" mode or "Plan Mode" (press `shift+tab` in Claude Code) first, and only let AI execute the step after you are satisfied.
- **Ultimate Vibe:** Install [Superwhisper](https://superwhisper.com) and chat casually with Claude or gpt-5.3-codex using voice, without typing.
</details>
<details>
<summary><strong>Workflow</strong></summary>
- After completing step 1:
- Commit changes to Git (ask AI if you don't know how).
- Start a new chat (`/new` or `/clear`).
- Prompt: Read all files in memory-bank, read progress.md to understand previous work progress, then continue with step 2 of the implementation plan. Do not start step 3 until I verify the tests.
- Repeat this process until the entire `implementation-plan.md` is completed.
</details>
</details>
<details>
<summary><strong>✨ Adding Detail Features</strong></summary>
Congratulations! You've built a basic game! It might still be rough and lack features, but now you can experiment and refine it as much as you want.
- Want fog effects, post-processing, special effects, sound effects? A better plane/car/castle? A beautiful sky?
- For each major feature added, create a new `feature-implementation.md` with short steps + tests.
- Continue incremental implementation and testing.
</details>
<details>
<summary><strong>🐞 Fixing Bugs and Getting Stuck</strong></summary>
<details>
<summary><strong>General Fixes</strong></summary>
- If a prompt fails or breaks the project:
- Use `/rewind` in Claude Code to revert; for gpt-5.3-codex, commit frequently with Git and reset when needed.
- Error handling:
- **JavaScript errors:** Open browser console (F12), copy error, paste to AI; for visual issues, send a screenshot.
- **Lazy solution:** Install [BrowserTools](https://browsertools.agentdesk.ai/installation) to automatically copy errors and screenshots.
</details>
<details>
<summary><strong>Difficult Issues</strong></summary>
- Really stuck:
- Revert to the previous git commit (`git reset`), try again with a new prompt.
- Extremely stuck:
- Use [RepoPrompt](https://repoprompt.com/) or [uithub](https://uithub.com/) to synthesize the entire codebase into one file, then send it to **gpt-5.3-codex or Claude** for help.
</details>
</details>
<details>
<summary><strong>💡 Tips and Tricks</strong></summary>
<details>
<summary><strong>Claude Code & Codex Usage Tips</strong></summary>
- **Terminal version of Claude Code / Codex CLI:** Run in VSCode terminal to directly view diffs and feed context without leaving the workspace.
- **Claude Code's `/rewind`:** Instantly revert to a previous state when iteration goes off track.
- **Custom commands:** Create shortcuts like `/explain $param` to trigger prompts: "Analyze the code in depth to thoroughly understand how $param works. Tell me after you understand, then I will give you a new task." This allows the model to fully load context before modifying code.
- **Clean up context:** Frequently use `/clear` or `/compact` (to retain conversation history).
- **Time-saving trick (use at your own risk):** Use `claude --dangerously-skip-permissions` or `codex --yolo` to completely disable confirmation pop-ups.
</details>
<details>
<summary><strong>Other Useful Tips</strong></summary>
- **Small modifications:** Use gpt-5.3-codex (medium)
- **Write top-tier marketing copy:** Use Opus 4.1
- **Generate excellent 2D sprites:** Use ChatGPT + Nano Banana
- **Generate music:** Use Suno
- **Generate sound effects:** Use ElevenLabs
- **Generate videos:** Use Sora 2
- **Improve prompt effectiveness:**
- Add a sentence: "Think slowly, no rush, it's important to strictly follow my instructions and execute perfectly. If my expression is not precise enough, please ask."
- In Claude Code, the intensity of keywords to trigger deep thinking: `think` < `think hard` < `think harder` < `ultrathink`.
</details>
</details>
<details>
<summary><strong>❓ Frequently Asked Questions (FAQ)</strong></summary>
- **Q: I'm making an app, not a game, is the process the same?**
- **A:** Essentially the same! Just replace GDD with PRD (Product Requirement Document). You can also quickly prototype with v0, Lovable, Bolt.new, then move the code to GitHub, and clone it locally to continue development using this guide.
- **Q: Your air combat game's plane model is amazing, but I can't make it with just one prompt!**
- **A:** That wasn't one prompt, it was ~30 prompts + a dedicated `plane-implementation.md` file guided it. Use precise instructions like "cut space for ailerons on the wing," instead of vague instructions like "make a plane."
- **Q: Why are Claude Code or Codex CLI stronger than Cursor now?**
- **A:** It's entirely a matter of personal preference. We emphasize that Claude Code can better leverage the power of Claude Opus 4.6, and Codex CLI can better leverage the power of gpt-5.3-codex. Cursor does not utilize either of these as well as their native terminal versions. Terminal versions can also work in any IDE, with SSH remote servers, etc., and features like custom commands, sub-agents, and hooks can significantly improve development quality and speed in the long run. Finally, even if you only have a low-tier Claude or ChatGPT subscription, it's completely sufficient.
- **Q: What if I don't know how to set up a multiplayer game server?**
- **A:** Ask your AI.
</details>
---
## 📞 Contact
- **GitHub**: [tukuaiai](https://github.com/tukuaiai)
- **Twitter / X**: [123olp](https://x.com/123olp)
- **Telegram**: [@desci0](https://t.me/desci0)
- **Telegram Group**: [glue_coding](https://t.me/glue_coding)
- **Telegram Channel**: [tradecat_ai_channel](https://t.me/tradecat_ai_channel)
- **Email**: tukuai.ai@gmail.com (replies might be delayed)
---
## ✨ Support Project
Please help us, thank you, good people will have a peaceful life 🙏🙏🙏
- **Binance UID**: `572155580`
- **Tron (TRC20)**: `TQtBXCSTwLFHjBqTS4rNUp7ufiGx51BRey`
- **Solana**: `HjYhozVf9AQmfv7yv79xSNs6uaEU5oUk2USasYQfUYau`
- **Ethereum (ERC20)**: `0xa396923a71ee7D9480b346a17dDeEb2c0C287BBC`
- **BNB Smart Chain (BEP20)**: `0xa396923a71ee7D9480b346a17dDeEb2c0C287BBC`
- **Bitcoin**: `bc1plslluj3zq3snpnnczplu7ywf37h89dyudqua04pz4txwh8z5z5vsre7nlm`
- **Sui**: `0xb720c98a48c77f2d49d375932b2867e793029e6337f1562522640e4f84203d2e`
---
### ✨ Contributors
Thanks to all developers who contributed to this project!
<a href="https://github.com/tukuaiai/vibe-coding-cn/graphs/contributors">
<img src="https://contrib.rocks/image?repo=tukuaiai/vibe-coding-cn" />
<img src="https://contrib.rocks/image?repo=EnzeD/vibe-coding" />
</a>
<p>Special thanks to the following members for their valuable contributions (in no particular order):<br/>
<a href="https://x.com/shao__meng">@shao__meng</a> |
<a href="https://x.com/0XBard_thomas">@0XBard_thomas</a> |
<a href="https://x.com/Pluvio9yte">@Pluvio9yte</a> |
<a href="https://x.com/xDinoDeer">@xDinoDeer</a> |
<a href="https://x.com/geekbb">@geekbb</a> |
<a href="https://x.com/GitHub_Daily">@GitHub_Daily</a> |
<a href="https://x.com/BiteyeCN">@BiteyeCN</a> |
<a href="https://x.com/CryptoJHK">@CryptoJHK</a>
</p>
---
## 🤝 Contributing
We warmly welcome all forms of contributions. If you have any ideas or suggestions for this project, please feel free to open an [Issue](https://github.com/tukuaiai/vibe-coding-cn/issues) or submit a [Pull Request](https://github.com/tukuaiai/vibe-coding-cn/pulls).
Before you start, please take the time to read our [**Contribution Guide (CONTRIBUTING.md)**](CONTRIBUTING.md) and [**Code of Conduct (CODE_OF_CONDUCT.md)**](CODE_OF_CONDUCT.md).
---
## 📜 License
This project is licensed under the [MIT](LICENSE) license.
---
<div align="center">
**If this project is helpful to you, please consider giving it a Star ⭐!**
## Star History
<a href="https://www.star-history.com/#tukuaiai/vibe-coding-cn&type=date&legend=top-left">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=tukuaiai/vibe-coding-cn&type=date&theme=dark&legend=top-left" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=tukuaiai/vibe-coding-cn&type=date&legend=top-left" />
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=tukuaiai/vibe-coding-cn&type=date&legend=top-left" />
</picture>
</a>
---
**Crafted with dedication by [tukuaiai](https://github.com/tukuaiai), [Nicolas Zullo](https://x.com/NicolasZu), and [123olp](https://x.com/123olp)**
[⬆ Back to Top](#vibe-coding-guide)
</div>

29
i18n/en/documents/-01-philosophy-and-methodology/AI Swarm Collaboration.md
View File

@ -1,29 +0,0 @@
# AI Swarm Collaboration
> Multi AI Agent collaboration system based on tmux
## Core Concept
Traditional mode: Human ←→ AI₁, Human ←→ AI₂, Human ←→ AI₃ (Human is the bottleneck)
Swarm mode: **Human → AI₁ ←→ AI₂ ←→ AI₃** (AI autonomous collaboration)
## Capability Matrix
| Capability | Implementation | Effect |
|:---|:---|:---|
| 🔍 Perception | `capture-pane` | Read any terminal content |
| 🎮 Control | `send-keys` | Send keystrokes to any terminal |
| 🤝 Coordination | Shared state files | Task synchronization and distribution |
## Core Breakthrough
AI is no longer isolated, but a cluster that can perceive, communicate, and control each other.
## Detailed Documentation
👉 [Deep Dive into AI Swarm Collaboration](../02-methodology/AI Swarm Collaboration - tmux Multi-Agent System.md)
## Related Resources
- [tmux Shortcut Cheatsheet](../02-methodology/tmux Shortcut Cheatsheet.md)

11
i18n/en/documents/-01-philosophy-and-methodology/Dialectics.md
View File

@ -1,11 +0,0 @@
Applying Dialectical Thesis-Antithesis-Synthesis to Vibe Coding: I treat each coding session as a round of "triadic progression"
Thesis (Current State): First let the model quickly provide the "smoothest implementation" based on intuition, with only one goal: get the main path running as soon as possible
Antithesis (Audit & Tuning): Immediately take the "critic" perspective and challenge it: list failure modes/edge cases/performance and security concerns, and ground the challenges with tests, types, lint, benchmarks
Synthesis (Correction Based on Review): Combine speed with constraints: refactor interfaces, converge dependencies, complete tests and documentation, forming a more stable starting point for the next round
Practice Mantra: Write smoothly first → Then challenge → Then converge
Vibe is responsible for generating possibilities, thesis-antithesis-synthesis is responsible for turning possibilities into engineering certainties

107
i18n/en/documents/-01-philosophy-and-methodology/Phenomenological Reduction.md
View File

@ -1,107 +0,0 @@
### Phenomenological Reduction (Suspension of Assumptions) for Vibe Coding
**Core Purpose**
Strip "what I think the requirement is" from the conversation, leaving only observable, reproducible, and verifiable facts and experience structures, allowing the model to produce usable code with fewer assumptions.
---
## 1) Key Methods (Understanding in Engineering Context)
* **Epoché (Suspension)**: Temporarily withhold any "causal explanations/business inferences/best practice preferences."
Only record: what happened, what is expected, what are the constraints.
* **Reduction**: Reduce the problem to the minimal structure of "given input → process → output."
Don't discuss architecture, patterns, or tech stack elegance first.
* **Intentionality**: Clarify "who this feature is for, in what context, to achieve what experience."
Not "make a login," but "users can complete login within 2 seconds even on weak networks and get clear feedback."
---
## 2) Applicable Scenarios
* Requirements descriptions full of abstract words: fast, stable, like something, intelligent, smooth.
* Model starts "bringing its own assumptions": filling in product logic, randomly selecting frameworks, adding complexity on its own.
* Hard to reproduce bugs: intermittent, environment-related, unclear input boundaries.
---
## 3) Operating Procedure (Can Follow Directly)
### A. First "Clear Explanations," Keep Only Phenomena
Describe using four elements:
1. **Phenomenon**: Actual result (including errors/screenshots/log fragments).
2. **Intent**: Desired result (observable criteria).
3. **Context**: Environment and preconditions (version, platform, network, permissions, data scale).
4. **Boundaries**: What not to do/not to assume (don't change interface, don't introduce new dependencies, don't change database structure, etc.).
### B. Produce "Minimal Reproducible Example" (MRE)
* Minimal input sample (shortest JSON/smallest table/smallest request)
* Minimal code snippet (remove unrelated modules)
* Clear reproduction steps (1, 2, 3)
* Expected vs. Actual (comparison table)
### C. Reduce "Abstract Words" to Testable Metrics
* "Fast" → P95 latency < X, cold start < Y, throughput >= Z
* "Stable" → Error rate < 0.1%, retry strategy, circuit breaker conditions
* "User-friendly" → Interaction feedback, error messages, undo/recovery capability
---
## 4) Prompt Templates for Models (Can Copy Directly)
**Template 1: Reduce Problem (No Speculation)**
```
Please first do "phenomenological reduction": don't speculate on causes, don't introduce extra features.
Based only on the information I provide, output:
1) Phenomenon (observable facts)
2) Intent (observable result I want)
3) Context (environment/constraints)
4) Undetermined items (minimum information that must be clarified or I need to provide)
5) Minimal reproducible steps (MRE)
Then provide the minimal fix solution and corresponding tests.
```
**Template 2: Abstract Requirements to Testable Specs**
```
Apply "suspension of assumptions" to the following requirements: remove all abstract words, convert to verifiable specs:
- Clear input/output
- Clear success/failure criteria
- Clear performance/resource metrics (if needed)
- Clear what NOT to do
Finally provide acceptance test case list.
Requirements: <paste>
```
---
## 5) Concrete Implementation in Vibe Coding (Building Habits)
* **Write "phenomenon card" before each work session** (2 minutes): phenomenon/intent/context/boundaries.
* **Have the model restate first**: require it to only restate facts and gaps, no solutions allowed.
* **Then enter generation**: solutions must be tied to "observable acceptance" and "falsifiable tests."
---
## 6) Common Pitfalls and Countermeasures
* **Pitfall: Treating explanations as facts** ("Might be caused by cache")
Countermeasure: Move "might" to "hypothesis list," each hypothesis with verification steps.
* **Pitfall: Requirements piled with adjectives**
Countermeasure: Force conversion to metrics and test cases; no writing code if not "testable."
* **Pitfall: Model self-selecting tech stack**
Countermeasure: Lock in boundaries: language/framework/dependencies/interfaces cannot change.
---
## 7) One-Sentence Mantra (Easy to Put in Toolbox Card)
**First suspend explanations, then fix phenomena; first write acceptance criteria, then let model write implementation.**

106
i18n/en/documents/-01-philosophy-and-methodology/README.md
View File

@ -1,106 +0,0 @@
# -01- Philosophy & Methodology: The Underlying Protocol of Vibe Coding
> **"Code is a projection of thought; philosophy is the operating system of thought."**
In the paradigm of Vibe Coding, we are no longer just "typists" but "architects of intention." This module transforms cross-disciplinary philosophical tools into executable engineering directives, aimed at eliminating cognitive friction in human-AI collaboration and enhancing the precision of intention delivery.
---
## Index
1. [Perception & Definition: Seeing the Truth](#1-perception--definition-seeing-the-truth)
2. [Logic & Refinement: Deep Reasoning](#2-logic--refinement-deep-reasoning)
3. [Verification & Correction: Countering Hallucinations](#3-verification--correction-countering-hallucinations)
4. [Systems & Evolution: Global Decision Making](#4-systems--evolution-global-decision-making)
5. [Frontier Cognitive Tools: Formalization & Computation](#5-frontier-cognitive-tools-formalization--computation)
---
## 1. Perception & Definition: Seeing the Truth
*Goal: Eliminate subjective bias and linguistic ambiguity before prompting.*
### Phenomenological Reduction
* **Method**: **Epoche (Suspension of Judgment)**. Describe "what is actually happening" rather than "what should happen."
* **Vibe App**: When describing bugs, provide raw logs and observed outputs; avoid injecting "I think it's this function" biases.
### Hermeneutics
* **Method**: **Hermeneutic Circle**. Understand the part through the whole and the whole through the part.
* **Vibe App**: Ask the model to restate requirements and list ambiguities before writing code.
### Steelmanning
* **Method**: Addressing the strongest possible version of an opponent's argument.
* **Vibe App**: In refactoring, ask: "Prove why my current solution is reasonable first, then propose a new one that surpasses it."
---
## 2. Logic & Refinement: Deep Reasoning
*Goal: Elevate the model's thinking depth towards optimal rather than just feasible solutions.*
### Socratic Questioning
* **Method**: Continuous inquiry. Why? What's the evidence? What's the counterexample?
* **Vibe App**: Use 5 layers of "Why" for model solutions, focusing on performance, edge cases, and graceful degradation.
### Occam's Razor
* **Method**: Entia non sunt multiplicanda praeter necessitatem (Entities should not be multiplied beyond necessity).
* **Vibe App**: Demand the model to "remove 30% complexity while keeping core requirements," favoring stateless designs.
### Bayesian Epistemology
* **Method**: Dynamically updating beliefs based on new evidence.
* **Vibe App**: Treat error logs as "new evidence" to update the prompt strategy via conditionalization, rather than repeating the same path.
---
## 3. Verification & Correction: Countering Hallucinations
*Goal: Establish scientific feedback loops to ensure code determinism.*
### Popperian Falsifiability
* **Method**: A theory that is not falsifiable is not scientific.
* **Vibe App**: Every "seemingly correct" code must have a test case that could prove it wrong. Shift from "I think it's right" to "I haven't falsified it yet."
### Counterfactual Thinking
* **Method**: Ask "What if X were not the case?"
* **Vibe App**: Build test matrices: What if the network times out? What if the disk is full? What if API returns are out of order?
### Experimental Philosophy (x-phi)
* **Method**: Using data to test intuitions.
* **Vibe App**: Don't argue over which API is better; generate A/B test scripts and let the benchmark data decide.
---
## 4. Systems & Evolution: Global Decision Making
*Goal: Maintain elegance in complex engineering, balancing speed and quality.*
### Systems Thinking / Holism
* **Method**: Focus on boundaries, feedback, and coupling.
* **Vibe App**: Visualize data flows and dependency graphs to decouple high-risk points and shorten feedback loops.
### Dialectical Contradiction Analysis
* **Method**: Identify and resolve the primary contradiction.
* **Vibe App**: When stuck, analyze if it's "unclear requirements," "unstable APIs," or "slow feedback." Resolve the core bottleneck first.
### Pragmatism
* **Method**: Truth is defined by its utility and effect.
* **Vibe App**: Define quantifiable metrics (P95 latency, cost, delivery time). Optimize one metric per iteration.
### Decision Theory
* **Method**: Distinguish between reversible and irreversible decisions.
* **Vibe App**: Label modifications as "fragile" or "foundational." Prioritize high-value, reversible actions (MVP).
---
## 5. Frontier Cognitive Tools: Formalization & Computation
* **Formal Methods**: Using math and modal logic to make epistemological problems computable and cumulative.
* **Computational Philosophy**: Using simulations and agent models to turn mental models into runnable experiments.
* **Reflective Equilibrium**: Iteratively calibrating specific judgments and general principles for systemic consistency.
* **Conceptual Engineering**: Actively engineering and optimizing conceptual tools to serve Vibe Coding practices.
---
## Detailed Method Guides
- [Phenomenological Reduction](./Phenomenological%20Reduction.md) - Suspension of assumptions for clear requirements
- [Dialectics](./Dialectics.md) - Thesis-Antithesis-Synthesis iterative development
---
*Note: This content evolves continuously as the supreme ideological directive of the Vibe Coding CN project.*

159
i18n/en/documents/00-fundamentals/A Formalization of Recursive Self-Optimizing Generative Systems.md
View File

@ -1,159 +0,0 @@
# A Formalization of Recursive Self-Optimizing Generative Systems
**tukuai**
Independent Researcher
GitHub: [https://github.com/tukuai](https://github.com/tukuai)
## Abstract
We study a class of recursive self-optimizing generative systems whose objective is not the direct production of optimal outputs, but the construction of a stable generative capability through iterative self-modification. The system generates artifacts, optimizes them with respect to an idealized objective, and uses the optimized artifacts to update its own generative mechanism. We provide a formal characterization of this process as a self-mapping on a space of generators, identify its fixed-point structure, and express the resulting self-referential dynamics using algebraic and λ-calculus formulations. The analysis reveals that such systems naturally instantiate a bootstrapping meta-generative process governed by fixed-point semantics.
---
## 1. Introduction
Recent advances in automated prompt engineering, meta-learning, and self-improving AI systems suggest a shift from optimizing individual outputs toward optimizing the mechanisms that generate them. In such systems, the object of computation is no longer a solution, but a *generator of solutions*.
This work formalizes a recursive self-optimizing framework in which a generator produces artifacts, an optimization operator improves them relative to an idealized objective, and a meta-generator updates the generator itself using the optimization outcome. Repeated application of this loop yields a sequence of generators that may converge to a stable, self-consistent generative capability.
Our contribution is a compact formal model capturing this behavior and a demonstration that the system admits a natural interpretation in terms of fixed points and self-referential computation.
---
## 2. Formal Model
Let (\mathcal{I}) denote an intention space and (\mathcal{P}) a space of prompts, programs, or skills. Define a generator space
$$
\mathcal{G} \subseteq \mathcal{P}^{\mathcal{I}},
$$
where each generator (G \in \mathcal{G}) is a function
$$
G : \mathcal{I} \to \mathcal{P}.
$$
Let (\Omega) denote an abstract representation of an ideal target or evaluation criterion. We define:
$$
O : \mathcal{P} \times \Omega \to \mathcal{P},
$$
an optimization operator, and
$$
M : \mathcal{G} \times \mathcal{P} \to \mathcal{G},
$$ a meta-generative operator that updates generators using optimized artifacts.
Given an initial intention (I \in \mathcal{I}), the system evolves as follows:
$$
P = G(I),
$$
$$
P^{*} = O(P, \Omega),
$$
$$
G' = M(G, P^{*}).
$$
---
## 3. Recursive Update Operator
The above process induces a self-map on the generator space:
$$
\Phi : \mathcal{G} \to \mathcal{G},
$$
defined by
$$
\Phi(G) = M\big(G,; O(G(I), \Omega)\big).
$$
Iteration of (\Phi) yields a sequence ({G_n}*{n \ge 0}) such that
$$G*{n+1} = \Phi(G_n).
$$
The system’s objective is not a particular (P^{*}), but the convergence behavior of the sequence ({G_n}).
---
## 4. Fixed-Point Semantics
A *stable generative capability* is defined as a fixed point of (\Phi):
$$G^{*} \in \mathcal{G}, \quad \Phi(G^{*}) = G^{*}.
$$
Such a generator is invariant under its own generate–optimize–update cycle. When (\Phi) satisfies appropriate continuity or contractiveness conditions, (G^{*}) can be obtained as the limit of iterative application:
$$G^{*} = \lim_{n \to \infty} \Phi^{n}(G_0).
$$
This fixed point represents a self-consistent generator whose outputs already encode the criteria required for its own improvement.
---
## 5. Algebraic and λ-Calculus Representation
The recursive structure can be expressed using untyped λ-calculus. Let (I) and (\Omega) be constant terms, and let (G), (O), and (M) be λ-terms. Define the single-step update functional:
$$
\text{STEP} ;\equiv; \lambda G.; (M;G)\big((O;(G;I));\Omega\big).
$$
Introduce a fixed-point combinator:
$$
Y ;\equiv; \lambda f.(\lambda x.f(x,x))(\lambda x.f(x,x)).
$$
The stable generator is then expressed as:
$$G^{*} ;\equiv; Y;\text{STEP},
$$
satisfying
$$G^{*} = \text{STEP};G^{*}.
$$
This formulation makes explicit the self-referential nature of the system: the generator is defined as the fixed point of a functional that transforms generators using their own outputs.
---
## 6. Discussion
The formalization shows that recursive self-optimization naturally leads to fixed-point structures rather than terminal outputs. The generator becomes both the subject and object of computation, and improvement is achieved through convergence in generator space rather than optimization in output space.
Such systems align with classical results on self-reference, recursion, and bootstrapping computation, and suggest a principled foundation for self-improving AI architectures and automated meta-prompting systems.
---
## 7. Conclusion
We presented a formal model of recursive self-optimizing generative systems and characterized their behavior via self-maps, fixed points, and λ-calculus recursion. The analysis demonstrates that stable generative capabilities correspond to fixed points of a meta-generative operator, providing a concise theoretical basis for self-improving generation mechanisms.
---
### Notes for arXiv submission
* **Category suggestions**: `cs.LO`, `cs.AI`, or `math.CT`
* **Length**: appropriate for extended abstract (≈3–4 pages LaTeX)
* **Next extension**: fixed-point existence conditions, convergence theorems, or proof sketches
---
## 附录：高层次概念释义 (Appendix: High-Level Conceptual Explanation)
The core idea of this paper can be popularly understood as an AI system capable of **self-improvement**. Its recursive nature can be broken down into the following steps:
#### 1. Define Core Roles:
* **α-Prompt (Generator)**: A "parent" prompt whose sole responsibility is to **generate** other prompts or skills.
* **Ω-Prompt (Optimizer)**: Another "parent" prompt whose sole responsibility is to **optimize** other prompts or skills.
#### 2. Describe the Recursive Lifecycle:
1. **Bootstrap**:
* Use AI to generate initial versions (v1) of `α-Prompt` and `Ω-Prompt`.
2. **Self-Correction & Evolution**:
* Use `Ω-Prompt (v1)` to **optimize** `α-Prompt (v1)`, obtaining a more powerful `α-Prompt (v2)`.
3. **Generation**:
* Use the **evolved** `α-Prompt (v2)` to generate **all** target prompts and skills we need.
4. **Recursive Loop**:
* The most crucial step: feed the newly generated, more powerful products (including new versions of `Ω-Prompt`) back into the system, again for optimizing `α-Prompt`, thereby initiating the next round of evolution.
#### 3. Ultimate Goal:
Through this never-ending **recursive optimization loop**, the system **self-transcends** in each iteration, infinitely approaching the **ideal state** we set.

45
i18n/en/documents/00-fundamentals/Code Organization.md
View File

@ -1,45 +0,0 @@
# Code Organization
## Modular Programming
- Divide code into small, reusable modules or functions, with each module responsible for doing only one thing.
- Use clear modular structures and directory structures to organize code, making it easier to navigate.
## Naming Conventions
- Use meaningful and consistent naming conventions so that the purpose of variables, functions, and classes can be understood from their names.
- Follow naming conventions, such as CamelCase for class names and snake_case for function and variable names.
## Code Comments
- Add comments to complex code segments to explain the code's functionality and logic.
- Use block comments (/*...*/) and line comments (//) to distinguish between different types of comments.
## Code Formatting
- Use consistent code style and formatting rules, and use tools like Prettier or Black to automatically format code.
- Use blank lines, indentation, and spaces to increase code readability.
# Documentation
## Docstrings
- Use docstrings at the beginning of each module, class, and function to explain its purpose, parameters, and return values.
- Choose a consistent docstring format, such as Google Style, NumPy/SciPy Style, or Sphinx Style.
## Automated Document Generation
- Use tools like Sphinx, Doxygen, or JSDoc to automatically generate documentation from code.
- Keep documentation and code synchronized to ensure documentation is always up-to-date.
## README File
- Include a detailed README file in the root directory of each project, explaining the project's purpose, installation steps, usage, and examples.
- Write README files using Markdown syntax to make them easy to read and maintain.
# Tools
## IDE
- Use powerful IDEs such as Visual Studio Code, PyCharm, or IntelliJ, leveraging their code auto-completion, error checking, and debugging features.
- Configure IDE plugins, such as linters (e.g., ESLint, Pylint) and code formatters.

577
i18n/en/documents/00-fundamentals/Code Review.md
View File

@ -1,577 +0,0 @@
```markdown
# Prompt for Code Review
Input: Purpose, Requirements, Constraints, Specifications
Output: Prompt for Review
Process: Input - Process - Output - Start a new session with the "Output" to analyze and check the specified file.
Repeat task until no issues (note: start a new session each time)
```
```prompt
################################################################################
# Executable, Auditable Engineering Checklist and Logic Verification System Prompt v1.0.0
################################################################################
====================
📌 META
=============
* Version: 1.0.0
* Models: GPT-4 / GPT-4.1 / GPT-5, Claude 3+ (Opus/Sonnet), Gemini Pro/1.5+
* Updated: 2025-12-19
* Author: PARE v3.0 Dual-Layer Standardized Prompt Architect
* License: Commercial/production use allowed; must retain this prompt's header meta-information; removal of "Quality Evaluation and Exception Handling" module is prohibited
====================
🌍 CONTEXT
================
### Background
In high-risk systems (finance/automation/AI/distributed), abstract requirements (such as "robustness", "security", "low complexity") if not engineered, can lead to non-auditable reviews, untestable coverage, and unverifiable deployments. This prompt is used to convert a set of informal specifications into an **executable, auditable, and reusable** checklist, and to perform item-by-item logical verification for each checkpoint, forming a formal engineering inspection document.
### Problem Definition
The input is a set of requirement specifications yi (possibly abstract and conflicting), along with project background and constraints; the output needs to achieve:
* Each yi is clearly defined (engineered) and marked with boundaries and assumptions.
* Exhaustive enumeration of decidable checkpoints (Yes/No/Unknown) for each yi.
* Item-by-item verification for each checkpoint, following "definition → necessity → verification method → passing standard".
* System-level analysis of conflicts/dependencies/alternatives between specifications, and providing prioritization and trade-off rationale.
### Target Users
* System Architects / R&D Leads / Quality Engineers / Security and Compliance Auditors
* Teams that need to translate requirements into "acceptable, accountable, and reusable" engineering inspection documents.
### Use Cases
* Architecture Review (Design Review)
* Compliance Audit (Audit Readiness)
* Deployment Acceptance and Gate (Release Gate)
* Postmortem and Defect Prevention
### Expected Value
* Transforms "abstract specifications" into "executable checkpoints + evidence chain"
* Significantly reduces omissions (Coverage) and ambiguities (Ambiguity)
* Forms reusable templates (cross-project migration) and auditable records (Audit Trail)
====================
👤 ROLE DEFINITION
==============
### Role Setting
You are a **world-class system architect + quality engineering expert + formal reviewer**, focusing on transforming informal requirements into an auditable engineering inspection system, and establishing a verification evidence chain for each checkpoint.
### Professional Capabilities
| Skill Area | Proficiency | Specific Application |
| ------------------------- | ----------- | --------------------------------------------- |
| System Architecture & Trade-offs | ■■■■■■■■■□ | System-level decisions for distributed/reliability/performance/cost |
| Quality Engineering & Testing System | ■■■■■■■■■□ | Test pyramid, coverage, gating strategy, regression and acceptance |
| Security & Compliance | ■■■■■■■■□□ | Threat modeling, permission boundaries, audit logs, compliance control mapping |
| Formal & Decidable Design | ■■■■■■■■□□ | Yes/No/Unknown checkpoint design, evidence chain and traceability |
| Runtime & SRE Governance | ■■■■■■■■■□ | Monitoring metrics, alerting strategy, drills, recovery, SLO/SLA |
### Experience Background
* Participated in/led architecture reviews, deployment gates, compliance audits, and postmortems for high-risk systems.
* Familiar with translating "specifications" into "controls → checkpoints (CP) → evidence".
### Code of Conduct
1. **No empty talk**: All content must be actionable, verifiable, and implementable.
2. **No skipping steps**: Strictly follow tasks 1-4 in order, closing each loop.
3. **Auditability first**: Each checkpoint must be decidable (Yes/No/Unknown), and the evidence type must be clear.
4. **Explicit conflicts**: If conflicts are found, they must be marked and trade-off and prioritization reasons provided.
5. **Conservative and secure**: In cases of insufficient information, treat as "Unknown + supplementary items", prohibit presumptive approval.
### Communication Style
* Structured, numbered, in an engineering document tone.
* Conclusions are upfront but must provide reviewable logic and verification methods.
* Use clear judgment conditions and thresholds (if missing, propose a set of optional thresholds).
====================
📋 TASK DESCRIPTION
==============
### Core Goal (SMART)
In a single output, generate a **complete checklist** for the input requirement specification set y1..yn, complete **item-by-item logical verification**, and then perform **system-level conflict/dependency/alternative analysis and prioritization recommendations**; the output should be directly usable for architecture review and compliance audit.
### Execution Flow
#### Phase 1: Input Absorption and Clarification (primarily without asking questions)
```
1.1 Parse project background fields (goal/scenarios/tech stack/constraints)
└─> Output: Background summary + key constraint list
1.2 Parse requirement specification list y1..yn (name/description/implicit goals)
└─> Output: Specification checklist table (including preliminary categories: reliability/security/performance/cost/complexity/compliance, etc.)
1.3 Identify information gaps
└─> Output: Unknown item list (for labeling only, does not block subsequent work)
```
#### Phase 2: Engineering Decomposition per Specification (Task 1 + Task 2)
```
2.1 Provide an engineered definition for each yi (measurable/acceptable)
└─> Output: Definition + boundaries + implicit assumptions + common failure modes
2.2 Exhaustively enumerate checkpoints for each yi (CP-yi-xx)
└─> Output: Decidable checkpoint list (Yes/No/Unknown)
2.3 Mark potential conflicts with other yj (mark first, do not elaborate)
└─> Output: Candidate conflict mapping table
```
#### Phase 3: Item-by-Item Logical Verification (Task 3)
```
3.1 For each CP: definition → necessity → verification method → passing standard
└─> Output: Verification description for each CP and acceptable/unacceptable judgment conditions
3.2 Clarify evidence chain (Evidence) artifacts
└─> Output: Evidence type (code/test report/monitoring screenshot/audit log/proof/drill record)
```
#### Phase 4: System-Level Analysis and Conclusion (Task 4)
```
4.1 Conflict/dependency/alternative relationship analysis
└─> Output: Relationship matrix + typical trade-off paths
4.2 Provide prioritization recommendations (including decision basis)
└─> Output: Prioritization list + rational trade-off reasons
4.3 Generate an audit-style ending for "whether all checks are complete"
└─> Output: Check coverage summary + outstanding items (Unknown) and supplementary actions
```
### Decision Logic (Mandatory Execution)
```
IF insufficient input information THEN
All critical information deficiencies are marked as Unknown
And provide a "Minimum Viable Checklist"
ELSE
Output "Full Checklist"
END IF
IF conflicts exist between specifications THEN
Explicitly list conflicting pairs (yi vs yj)
Provide trade-off principles (e.g., Security/Compliance > Reliability > Data Correctness > Availability > Performance > Cost > Complexity)
And provide optional decision paths (Path A/B/C)
END IF
```
====================
🔄 INPUT/OUTPUT (I/O)
==============
### Input Specification (Must Comply)
```json
{
"required_fields": {
"context": {
"project_goal": "string",
"use_scenarios": "string | array",
"tech_stack_env": "string | object",
"key_constraints": "string | array | object"
},
"requirements_set": [
{
"id": "string (e.g., y1)",
"name": "string (e.g., Robustness)",
"description": "string (can be abstract)"
}
]
},
"optional_fields": {
"risk_class": "enum[low|medium|high] (default: high)",
"compliance_targets": "array (default: [])",
"non_goals": "array (default: [])",
"architecture_summary": "string (default: null)"
},
"validation_rules": [
"requirements_set length >= 1",
"Each requirement must include id/name/description (description can be empty but not recommended)",
"If risk_class=high, then security/audit/recovery related CPs must be output (even if the user does not explicitly list them)"
]
}
```
### Output Template (Must Strictly Comply)
```
【Background Summary】
- Project Goal:
- Use Scenarios:
- Tech Stack/Environment:
- Key Constraints:
- Risk Level/Compliance Targets:
【Specification Item Output】
Output for each yi according to the following structure:
#### yi：<Specification Name>
1. Specification Definition (Engineered)
2. Scope and Boundaries
3. Complete Checklist
- CP-yi-01:
- CP-yi-02:
- ...
4. Item-by-Item Logical Check
- CP-yi-01:
- Definition:
- Necessity:
- Verification Method:
- Passing Standard:
- ...
5. Relationship Analysis with Other Specifications
【System-Level Analysis】
- Conflict Relationships:
- Strong Dependency Relationships:
- Substitutable Relationships:
- Prioritization Recommendation:
- Trade-off Decision Basis:
【Audit-Style Wrap-up】
- Total Covered Checkpoints:
- Unknown Items and Supplementary Actions:
- Criteria for "Is Everything Checked":
```
====================
💡 EXAMPLES
=================
### Example 1: Basic Scenario (Abstract Specification → Decidable CP)
**Input:**
```
context:
project_goal: "Build an automated trading risk control service"
use_scenarios: ["Pre-order risk control interception", "Real-time position risk calculation"]
tech_stack_env: "Python + Redis + Postgres + K8s"
key_constraints: ["Latency<20ms", "High availability", "Auditable", "Cost constrained"]
requirements_set:
- id: "y1"
name: "Robustness"
description: "Service can still run under abnormal conditions"
- id: "y2"
name: "Security"
description: "Prevent unauthorized access and data leakage"
```
**Output (Excerpt):**
```
#### y1：Robustness
1. Specification Definition (Engineered)
- Under dependent failures, abnormal inputs, and resource fluctuations, the system maintains core path availability or controlled degradation; errors do not spread; data is not irreversibly corrupted.
3. Complete Checklist
- CP-y1-01: Are timeouts and retry limits set for all external dependencies (Redis/Postgres/third-party API)? (Y/N/U)
- CP-y1-02: Are there circuit breaking/rate limiting/isolation strategies in place and configurable? (Y/N/U)
- CP-y1-03: Are there clear degradation paths for key abnormal scenarios (return codes/caching/read-only mode)? (Y/N/U)
4. Item-by-Item Logical Check
- CP-y1-01:
- Definition: Verify that external dependency failures do not cause permanent blocking of threads/coroutines.
- Necessity: Ignoring this will lead to cascading failures, queue amplification, and overall unavailability.
- Verification Method: Code review (timeout parameter), fault injection (network outage/latency), stress testing observation.
- Passing Standard: P99 latency does not exponentially increase with dependency failure; no infinite retries; timeouts have upper limits and are traceable in logs.
```
---
### Example 2: Advanced Scenario (Explicit Conflict between Performance vs Security)
**Input:**
```
requirements_set:
- id: "y1"
name: "Optimal Performance"
description: "Lower latency is better"
- id: "y2"
name: "Security"
description: "All requests must be authenticated and audited"
```
**Output (Excerpt):**
```
【System-Level Analysis - Conflict Relationships】
- Conflict: y1 (Performance) vs y2 (Security/Audit)
- Decision Basis: When risk_class=high, security and audit take precedence.
- Trade-off Paths:
Path A: Strong authentication + asynchronous auditing (reduces main path overhead)
Path B: Strong authentication + sampled auditing (requires compliance permission)
Path C: Gateway unified authentication + minimal in-service verification (requires clear responsibility boundaries)
```
---
### Example 3: Edge Case (Insufficient Information Still Outputs Minimum Viable Checklist)
**Input:**
```
context:
project_goal: "A service"
use_scenarios: ""
tech_stack_env: ""
key_constraints: ""
requirements_set:
- id: "y1"
name: "Completeness"
description: ""
```
**Output (Excerpt):**
```
【Unknown Items and Supplementary Actions】
- Unknown: Business critical paths, data consistency requirements, compliance targets, RTO/RPO
- Supplementary Actions: Provide interface list, data flow, failure severity definitions
【Minimum Viable Checklist (MVC)】
- CP-y1-01: Is there a clear "functional scope list" (In-scope/Out-of-scope)? (Y/N/U)
- CP-y1-02: Is there a traceability matrix from requirements → design → implementation → testing? (Y/N/U)
...
```
### ❌ Incorrect Example (Avoid This)
```
建议你提高健壮性、安全性，做好测试和监控。
```
**Problem:** Not decidable, not auditable, no checkpoint numbering, no verification method or passing standard, cannot be used for review and gating.
====================
📊 QUALITY EVALUATION
====================
### Scoring Standard (Total 100 points)
| Evaluation Dimension | Weight | Scoring Standard |
| ---------------- | ------ | -------------------------------------- |
| Decidability | 30% | ≥95% of checkpoints are clearly decidable Yes/No/Unknown |
| Coverage Completeness | 25% | For each yi, covers design/implementation/operations/boundaries/conflicts |
| Verifiability | 20% | Each CP provides an executable verification method and evidence type |
| Auditability | 15% | Consistent numbering, clear evidence chain, traceable to requirements |
| System-level Trade-off | 10% | Conflict/dependency/alternative analysis is clear and has decision basis |
### Quality Checklist
#### Must Satisfy (Critical)
* [ ] Each yi includes: Definition/Boundaries/Checklist/Item-by-Item Logical Check/Relationship Analysis
* [ ] Each CP is decidable (Yes/No/Unknown) and has a passing standard
* [ ] Output includes system-level conflict/dependency/alternative and prioritization recommendations
* [ ] All insufficient information is marked Unknown, and supplementary actions are provided
#### Should Satisfy (Important)
* [ ] Checkpoint coverage: Design/Implementation/Runtime/Operations/Exceptions & Boundaries
* [ ] For high-risk systems, default inclusion of: Audit logs, recovery drills, permission boundaries, data correctness
#### Recommended (Nice to have)
* [ ] Provide "Minimum Viable Checklist (MVC)" and "Full Checklist" tiers
* [ ] Provide reusable templates (can be copied to next project)
### Performance Benchmark
* Output structure consistency: 100% (title levels and numbering format remain unchanged)
* Iterations: ≤2 (first provides complete, second refines based on supplementary information)
* Evidence chain coverage: ≥80% of CPs clearly define evidence artifact types
====================
⚠️ EXCEPTION HANDLING
====================
### Scenario 1: User's specifications are too abstract/empty descriptions
```
Trigger condition: yi.description is empty or only 1-2 words (e.g., "better", "stable")
Handling plan:
1) First provide "optional interpretation set" for engineered definitions (2-4 types)
2) Still output checkpoints, but mark critical parts as Unknown
3) Provide a minimal list of supplementary questions (does not block)
Fallback strategy: Output "Minimum Viable Checklist (MVC)" + "List of information to be supplemented"
```
### Scenario 2: Strong conflicts between specifications and no prioritization information
```
Trigger condition: Simultaneously requests "extreme performance/lowest cost/highest security/zero complexity" etc.
Handling plan:
1) Explicitly list conflicting pairs and reasons for conflict
2) Provide default prioritization (high-risk: security/compliance first)
3) Offer optional decision paths (A/B/C) and consequences
Fallback strategy: Provide "Acceptable Compromise Set" and "List of Must-Decide Points"
```
### Scenario 3: Checkpoints cannot be binary decided
```
Trigger condition: CP is naturally a continuous quantity (e.g., "performance is fast enough")
Handling plan:
1) Rewrite CP as a judgment of "threshold + measurement + sampling window"
2) If threshold is unknown, provide candidate threshold ranges and mark as Unknown
Fallback strategy: Replace absolute thresholds with "relative thresholds" (no degradation) + baseline comparison (benchmark)
```
### Error Message Template (Must output in this format)
```
ERROR_001: "Insufficient input information: missing <field>, related checkpoints will be marked as Unknown."
Suggested action: "Please supplement <field> (example: ...) to converge Unknown to Yes/No."
ERROR_002: "Specification conflict found: <yi> vs <yj>."
Suggested action: "Please choose prioritization or accept a trade-off path (A/B/C). If not chosen, will be handled according to high-risk default priority."
```
### Degradation Strategy
When unable to output a "Full Checklist":
1. Output MVC (Minimum Viable Checklist)
2. Output Unknown and supplementary actions
3. Output conflicts and must-decide points (no presumptive conclusions)
====================
🔧 USAGE INSTRUCTIONS
=======
### Quick Start
1. Copy the "【Main Prompt for Direct Input】" below into the model.
2. Paste your context and requirements_set.
3. Run directly; if Unknown appears, supplement according to "supplementary actions" and run again.
### Parameter Tuning Recommendations
* For stricter audit: Set risk_class to high, and fill in compliance_targets.
* For shorter output: Request "only output checklist + passing standard", but **do not allow removal of exception handling and system-level analysis**.
* For more executable: Request each CP to include "evidence sample filename/metric name/log field name".
### Version Update Record
* v1.0.0 (2025-12-19): First release; supports yi engineering, CP enumeration, item-by-item logical verification, system-level trade-offs.
################################################################################
# 【Main Prompt for Direct Input】
################################################################################
You will act as: **world-class system architect + quality engineering expert + formal reviewer**.
Your task is: **for the project requirements I provide, build a complete "executable, auditable, reusable" inspection checklist, and perform item-by-item logical verification**.
Output must be used for: architecture review, compliance audit, high-risk system gating; no empty talk; no skipping steps; all checkpoints must be decidable (Yes/No/Unknown).
---
## Input (I will provide)
* Project Context
* Project Goal:
* Use Scenarios:
* Tech Stack/Runtime Environment:
* Key Constraints (computational power/cost/compliance/real-time, etc.):
* Requirement Specification Set
* y1...yn: May be abstract, informal
---
## Your Mandatory Tasks (All)
### Task 1: Requirement Semantic Decomposition
For each yi:
* Provide **engineered definition**
* Point out **applicable boundaries and implicit assumptions**
* Provide **common failure modes/misinterpretations**
### Task 2: Checklist Enumeration
For each yi, **exhaustively list** all mandatory check points (at least covering):
* Design level
* Implementation level
* Runtime/Operations level
* Extreme/Boundary/Exception scenarios
* Potential conflicts with other yj
Requirements: Each checkpoint must be decidable (Yes/No/Unknown), no ambiguous statements merged; use numbering: CP-yi-01...
### Task 3: Item-by-Item Logical Check
For each checkpoint CP:
1. **Definition**: What is being verified?
2. **Necessity**: What happens if it's ignored?
3. **Verification Method**: Code review/testing/proof/monitoring metrics/simulation/drills (at least one)
4. **Passing Standard**: Clearly acceptable and unacceptable judgment conditions (including thresholds or baselines; if unknown, mark as Unknown and provide candidate thresholds)
### Task 4: System-Level Analysis of Specifications
* Analyze conflicts/strong dependencies/substitutability between yi and yj
* Provide **prioritization recommendations**
* If trade-offs exist, provide **rational decision basis** (high-risk default: security/compliance first)
---
## Output Format (Must Strictly Comply)
First output 【Background Summary】, then for each yi output according to the following structure:
#### yi: <Specification Name>
1. **Specification Definition (Engineered)**
2. **Scope and Boundaries**
3. **Complete Checklist**
* CP-yi-01:
* CP-yi-02:
* ...
4. **Item-by-Item Logical Check**
* CP-yi-01:
* Definition:
* Necessity:
* Verification Method:
* Passing Standard:
* ...
5. **Relationship Analysis with Other Specifications**
Finally output 【System-Level Analysis】 and 【Audit-Style Wrap-up】:
* Total covered checkpoints
* Unknown items and supplementary actions
* Criteria for "Is everything checked" (how to converge from Unknown to Yes/No)
---
## Constraints and Principles (Mandatory)
* No empty suggestive talk; no skipping logic; no skipping steps
* All insufficient information must be marked Unknown, and supplementary actions provided; no presumptive approval
* Output must be sufficient to answer:
**"To satisfy y1..yn, what exactly do I need to check? Have I checked everything?"**
Start execution: Waiting for me to provide Context and Requirements Set.
```
```

479
i18n/en/documents/00-fundamentals/Common Pitfalls.md
View File

@ -1,479 +0,0 @@
```markdown
# 🕳️ Common Pitfalls Summary
> Common issues and solutions during the Vibe Coding process
---
<details open>
<summary><strong>🤖 AI Conversation Related</strong></summary>
| Problem | Reason | Solution |
|:---|:---|:---|
| AI generated code doesn't run | Insufficient context | Provide full error message, explain execution environment |
| AI repeatedly modifies the same issue | Stuck in a loop | Try a different approach, or start a new conversation |
| AI hallucination, fabricating non-existent APIs | Outdated model knowledge | Provide official documentation link for AI reference |
| Code becomes messier after AI modifications | Lack of planning | Have AI propose a plan first, then confirm before coding |
| AI doesn't understand my requirements | Vague description | Use concrete examples, provide input/output samples |
| AI forgets previous conversation | Context loss | Re-provide key information, or use memory bank |
| AI modifies code it shouldn't have | Unclear instructions | Explicitly state "only modify xxx, don't touch other files" |
| AI generated code style is inconsistent | No style guide | Provide code style guide or example code |
</details>
---
<details open>
<summary><strong>🐍 Python Virtual Environment Related</strong></summary>
### Why use a virtual environment?
- Avoid dependency conflicts between different projects
- Keep the system Python clean
- Easy to reproduce and deploy
### Create and use .venv
```bash
# Create virtual environment
python -m venv .venv
# Activate virtual environment
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Deactivate virtual environment
deactivate
```
### Common Problems
| Problem | Reason | Solution |
|:---|:---|:---|
| Environment setup always fails | Global pollution | Delete and restart, isolate with `.venv` virtual environment |
| `python` command not found | Virtual environment not activated | Run `source .venv/bin/activate` first |
| Package installed but import error | Installed globally | Confirm virtual environment is active before `pip install` |
| Dependency conflicts between projects | Sharing global environment | Create a separate `.venv` for each project |
| VS Code uses wrong Python interpreter | Interpreter not selected correctly | Ctrl+Shift+P → "Python: Select Interpreter" → choose .venv |
| pip version too old | Virtual environment defaults to old version | `pip install --upgrade pip` |
| requirements.txt missing dependencies | Not exported | `pip freeze > requirements.txt` |
### One-click environment reset
Environment completely messed up? Delete and restart:
```bash
# Delete old environment
rm -rf .venv
# Recreate
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
</details>
---
<details open>
<summary><strong>📦 Node.js Environment Related</strong></summary>
### Common Problems
| Problem | Reason | Solution |
|:---|:---|:---|
| Node version mismatch | Project requires specific version | Use nvm to manage multiple versions: `nvm install 18` |
| `npm install` error | Network/Permissions issue | Change registry, clear cache, delete node_modules and reinstall |
| Global package not found | PATH not configured | Add `npm config get prefix` to PATH |
| package-lock conflict | Collaborative work | Consistently use `npm ci` instead of `npm install` |
| node_modules too large | Normal phenomenon | Add to .gitignore, do not commit |
### Common Commands
```bash
# Change to Taobao registry
npm config set registry https://registry.npmmirror.com
# Clear cache
npm cache clean --force
# Delete and reinstall
rm -rf node_modules package-lock.json
npm install
# Switch Node version with nvm
nvm use 18
```
</details>
---
<details open>
<summary><strong>🔧 Environment Configuration Related</strong></summary>
| Problem | Reason | Solution |
|:---|:---|:---|
| Command not found | Environment variable not configured | Check PATH, restart terminal |
| Port in use | Not properly closed last time | `lsof -i :port_number` or `netstat -ano \| findstr :port_number` |
| Insufficient permissions | Linux/Mac permissions | `chmod +x` or `sudo` |
| Environment variables not taking effect | Not sourced | `source ~/.bashrc` or restart terminal |
| .env file not taking effect | Not loaded | Use `python-dotenv` or `dotenv` package |
| Windows path issues | Backslashes | Use `/` or `\\` or `Path` library |
</details>
---
<details open>
<summary><strong>🌐 Network Related</strong></summary>
| Problem | Reason | Solution |
|:---|:---|:---|
| GitHub access slow/timeout | Network restrictions | Configure proxy, refer to [Network Environment Configuration](../从零开始vibecoding/01-网络环境配置.md) |
| API call failed | Network/Key issue | Check proxy, API Key validity |
| Terminal not using proxy | Incomplete proxy configuration | Set environment variables (see below) |
| SSL certificate error | Proxy/Time issue | Check system time, or temporarily disable SSL verification |
| pip/npm download slow | Source abroad | Use domestic mirror source |
| git clone timeout | Network restrictions | Configure git proxy or use SSH |
### Terminal Proxy Configuration
```bash
# Temporary setting (effective for current terminal)
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
# Permanent setting (add to ~/.bashrc or ~/.zshrc)
echo 'export http_proxy=http://127.0.0.1:7890' >> ~/.bashrc
echo 'export https_proxy=http://127.0.0.1:7890' >> ~/.bashrc
source ~/.bashrc
# Git Proxy
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890
```
</details>
---
<details open>
<summary><strong>📝 Code Related</strong></summary>
| Problem | Reason | Solution |
|:---|:---|:---|
| Code file too large, AI cannot process | Exceeds context | Split files, only provide relevant parts to AI |
| Modified code not taking effect | Cache/Not saved | Clear cache, confirm save, restart service |
| Merge conflicts | Git conflict | Let AI help resolve: paste conflict content |
| Dependency version conflicts | Version incompatibility | Specify version number, or isolate with virtual environment |
| Chinese garbled characters | Encoding issue | Unify to UTF-8, add `# -*- coding: utf-8 -*-` at file beginning |
| Hot update not taking effect | Listening issue | Check if file is within listening range |
</details>
---
<details open>
<summary><strong>🎯 Claude Code / Cursor Related</strong></summary>
| Problem | Reason | Solution |
|:---|:---|:---|
| Claude Code cannot connect | Network/Authentication | Check proxy, re-`claude login` |
| Cursor completion is slow | Network latency | Check proxy configuration |
| Quota used up | Limited free quota | Switch accounts or upgrade to paid |
| Rule file not taking effect | Path/Format error | Check `.cursorrules` or `CLAUDE.md` location |
| AI cannot read project files | Workspace issue | Confirm opened in correct directory, check .gitignore |
| Generated code in wrong location | Cursor position | Place cursor at correct position before generating |
</details>
---
<details open>
<summary><strong>🚀 Deployment Related</strong></summary>
| Problem | Reason | Solution |
|:---|:---|:---|
| Runs locally, but fails to deploy | Environment differences | Check Node/Python versions, environment variables |
| Build timeout | Project too large | Optimize dependencies, increase build time limit |
| Environment variables not taking effect | Not configured | Set environment variables on deployment platform |
| CORS cross-origin error | Backend not configured | Add CORS middleware |
| Static files 404 | Path issue | Check build output directory configuration |
| Insufficient memory | Free tier limitations | Optimize code or upgrade plan |
</details>
---
<details open>
<summary><strong>🗄️ Database Related</strong></summary>
| Problem | Reason | Solution |
|:---|:---|:---|
| Connection refused | Service not started | Start database service |
| Authentication failed | Incorrect password | Check username and password, reset password |
| Table does not exist | Not migrated | Run migration |
| Data loss | Not persisted | Docker with volume, or use cloud database |
| Too many connections | Connections not closed | Use connection pool, close connections promptly |
</details>
---
<details open>
<summary><strong>🐳 Docker Related</strong></summary>
| Problem | Reason | Solution |
|:---|:---|:---|
| Image pull failed | Network issue | Configure image accelerator |
| Container failed to start | Port conflict/Configuration error | Check logs `docker logs container_name` |
| File changes not taking effect | Volume not mounted | Add `-v` parameter to mount directory |
| Insufficient disk space | Too many images | `docker system prune` to clean up |
</details>
---
<details open>
<summary><strong>🧠 Large Language Model Usage Related</strong></summary>
| Problem | Reason | Solution |
|:---|:---|:---|
| Token limit exceeded | Input too long | Refine context, only provide necessary information |
| Reply truncated | Output token limit | Ask AI to output in segments, or say "continue" |
| Significant differences in results between models | Different model characteristics | Choose model based on task: Claude for code, GPT for general purpose |
| Temperature parameter effect | Temperature setting | Use low temperature (0-0.3) for code generation, high for creativity |
| System prompt ignored | Prompt too long/conflicting | Simplify system prompt, put important parts first |
| JSON output format error | Model unstable | Use JSON mode, or ask AI to output only code blocks |
| Multi-turn conversation quality degrades | Context pollution | Regularly start new conversations, keep context clean |
| API call returns 429 error | Rate limit | Add delayed retries, or upgrade API plan |
| Streaming output garbled | Encoding/Parsing issue | Check SSE parsing, ensure UTF-8 |
</details>
---
<details open>
<summary><strong>🏗️ Software Architecture Related</strong></summary>
| Problem | Reason | Solution |
|:---|:---|:---|
| Code becomes messier | No architectural design | Draw architecture diagram first, then write code |
| Changing one place breaks others | Too tightly coupled | Split modules, define clear interfaces |
| Don't know where to put code | Directory structure messy | Refer to [General Project Architecture Template](../模板与资源/通用项目架构模板.md) |
| Too much duplicate code | No abstraction | Extract common functions/components |
| State management chaotic | Overuse of global state | Use state management libraries, one-way data flow |
| Configuration scattered | No unified management | Centralize in config files or environment variables |
| Difficult to test | Too many dependencies | Dependency injection, mock external services |
</details>
---
<details open>
<summary><strong>🔄 Git Version Control Related</strong></summary>
| Problem | Reason | Solution |
|:---|:---|:---|
| Committed files that shouldn't be | .gitignore not configured | Add to .gitignore, `git rm --cached` |
| Committed sensitive information | Not checked | Use git-filter-branch to clean history, change key |
| Don't know how to resolve merge conflicts | Unfamiliar with Git | Use VS Code conflict resolution tools, or ask AI for help |
| Committed with wrong message | Mistake | `git commit --amend` to modify |
| Want to undo last commit | Committed wrongly | `git reset --soft HEAD~1` |
| Too many messy branches | No standard | Use Git Flow or trunk-based |
| Push rejected | New commits on remote | `pull --rebase` first, then push |
### Common Git Commands
```bash
# Discard changes in working directory
git checkout -- filename
# Discard changes in staging area
git reset HEAD filename
# Undo last commit (keep changes)
git reset --soft HEAD~1
# View commit history
git log --oneline -10
# Stash current changes
git stash
git stash pop
```
</details>
---
<details open>
<summary><strong>🧪 Testing Related</strong></summary>
| Problem | Reason | Solution |
|:---|:---|:---|
| Don't know what to test | Lack of testing mindset | Test edge cases, abnormal situations, core logic |
| Tests are too slow | Test granularity too large | Write more unit tests, fewer E2E |
| Tests are unstable | Dependent on external services | Mock external dependencies |
| Tests pass but bugs appear online | Incomplete coverage | Add edge case tests, check with coverage |
| Changing code requires changing tests | Tests coupled to implementation | Test behavior, not implementation |
| AI generated tests are useless | Only tests happy path | Ask AI to supplement edge case and abnormal tests |
</details>
---
<details open>
<summary><strong>⚡ Performance Related</strong></summary>
| Problem | Reason | Solution |
|:---|:---|:---|
| Page loading slow | Resources too large | Compression, lazy loading, CDN |
| API response slow | Unoptimized queries | Add index, caching, pagination |
| Memory leak | Resources not cleaned up | Check event listeners, timers, closures |
| High CPU usage | Infinite loop/Repetitive calculation | Use profiler to locate hot spots |
| Slow database queries | N+1 problem | Use JOIN or batch queries |
| Frontend stuttering | Too many re-renders | React.memo, useMemo, virtual list |
</details>
---
<details open>
<summary><strong>🔐 Security Related</strong></summary>
| Problem | Reason | Solution |
|:---|:---|:---|
| API Key leaked | Committed to Git | Use environment variables, add to .gitignore |
| SQL injection | String concatenation for SQL | Use parameterized queries/ORM |
| XSS attack | User input not escaped | Escape HTML, use CSP |
| CSRF attack | No token verification | Add CSRF token |
| Passwords stored in plaintext | Lack of security awareness | Use bcrypt or other hashing algorithms |
| Sensitive information in logs | Printed what shouldn't be | Anonymize data, disable debug in production |
</details>
---
<details open>
<summary><strong>📱 Frontend Development Related</strong></summary>
| Problem | Reason | Solution |
|:---|:---|:---|
| Styles not taking effect | Priority/Cache | Check selector priority, clear cache |
| Mobile adaptation issues | No responsive design | Use rem/vw, media queries |
| White screen | JS error | Check console, add error boundaries |
| State not synchronized | Asynchronous issues | Use useEffect dependencies, or state management library |
| Component not updating | Reference not changed | Return new object/array, do not modify directly |
| Bundle size too large | No optimization | On-demand import, code splitting, tree shaking |
| Cross-origin issue | Browser security policy | Backend configure CORS, or use proxy |
</details>
---
<details open>
<summary><strong>🖥️ Backend Development Related</strong></summary>
| Problem | Reason | Solution |
|:---|:---|:---|
| API response slow | Synchronous blocking | Use asynchronous, put time-consuming tasks in queue |
| Concurrency issues | Race conditions | Add locks, use transactions, optimistic locking |
| Service crashed without detection | No monitoring | Add health checks, alerts |
| Logs not helping to find issues | Incomplete logs | Add request_id, structured logging |
| Different environment configuration | Hardcoding | Use environment variables to distinguish dev/prod |
| OOM crashes | Memory leak/Too much data | Paging, streaming, check for leaks |
</details>
---
<details open>
<summary><strong>🔌 API Design Related</strong></summary>
| Problem | Reason | Solution |
|:---|:---|:---|
| API naming chaotic | No standard | Follow RESTful, use HTTP methods as verbs |
| Return format inconsistent | No agreement | Unify response structure `{code, data, message}` |
| Version upgrade difficult | No version control | Add version number to URL `/api/v1/` |
| Documentation and implementation inconsistent | Manual maintenance | Use Swagger/OpenAPI to auto-generate |
| Error messages unclear | Only returns 500 | Refine error codes, return useful information |
| Pagination parameters inconsistent | Each written differently | Unify `page/size` or `offset/limit` |
</details>
---
<details open>
<summary><strong>📊 Data Processing Related</strong></summary>
| Problem | Reason | Solution |
|:---|:---|:---|
| Data format incorrect | Type conversion issue | Perform type validation and conversion properly |
| Timezone issues | Timezones not unified | Store in UTC, convert to local for display |
| Precision loss | Floating-point issues | Use integers for currency (cents), or Decimal |
| Large file processing OOM | Loaded all at once | Stream processing, chunked reading |
| Encoding issues | Not UTF-8 | Unify to UTF-8, specify encoding when reading files |
| Null value handling | null/undefined | Perform null checks, provide default values |
</details>
---
<details open>
<summary><strong>🤝 Collaboration Related</strong></summary>
| Problem | Reason | Solution |
|:---|:---|:---|
| Code style inconsistent | No standard | Use ESLint/Prettier/Black, unify configuration |
| PR too large, difficult to review | Too many changes | Small, incremental commits, one PR per feature |
| Documentation outdated | No one maintains | Update code and documentation together, CI check |
| Don't know who is responsible | No owner | Use CODEOWNERS file |
| Reinventing the wheel | Unaware of existing solutions | Establish internal component library/documentation |
</details>
1. **Check error message** - Copy it completely to AI
2. **Minimal reproduction** - Find the simplest code that reproduces the issue
3. **Bisection method** - Comment out half of the code, pinpoint the problem area
4. **Change environment** - Try a different browser/terminal/device
5. **Restart magic** - Restart service/editor/computer
6. **Delete and restart** - If the environment is messy, delete and recreate the virtual environment
---
## 🔥 Ultimate Solution
Still can't figure it out? Try this prompt:
```
I encountered a problem and have tried many methods without success.
Error message:
[Paste full error]
My environment:
- Operating System:
- Python/Node Version:
- Relevant dependency versions:
I have already tried:
1. xxx
2. xxx
Please help me analyze possible causes and provide solutions.
```
---
## 📝 Contribution
Found a new pitfall? Welcome to PR to supplement!
```

221
i18n/en/documents/00-fundamentals/Development Experience.md
View File

@ -1,221 +0,0 @@
# **Development Experience and Project Specification Organization Document**
## Table of Contents
1. Variable Name Maintenance Solution
2. File Structure and Naming Conventions
3. Coding Style Guide
4. System Architecture Principles
5. Core Ideas of Program Design
6. Microservices
7. Redis
8. Message Queue
---
# **1. Variable Name Maintenance Solution**
## 1.1 Create a "Comprehensive Variable Name File"
Establish a unified variable index file for AI and overall team maintenance.
### File content includes (format example):
| Variable Name | Variable Comment (Description) | Location (File Path) | Frequency (Statistics) |
| :------------ | :----------------------------- | :------------------------- | :--------------------- |
| user_age | User age | /src/user/profile.js | 12 |
### Purpose
* Unified variable naming
* Convenient global search
* AI or human can uniformly manage and refactor
* Reduce the risk of naming conflicts and unclear semantics
---
# **2. File Structure and Naming Conventions**
## 2.1 Subfolder Content
Each subdirectory needs to contain:
* `agents` - Responsible for automation processes, prompts, agent logic
* `claude.md` - Stores documentation, design ideas, and usage for the content of this folder
## 2.2 File Naming Rules
* Use **lowercase English + underscore** or **camelCase** (depending on the language)
* Filenames should reflect content responsibilities
* Avoid abbreviations and ambiguous naming
Examples:
* `user_service.js`
* `order_processor.py`
* `config_loader.go`
## 2.3 Variable and Definition Rules and Explanations
* Naming should be as semantic as possible
* Follow English grammatical logic (noun attributes, verb behaviors)
* Avoid meaningless names like `a, b, c`
* Constants use uppercase + underscore (e.g., `MAX_RETRY_COUNT`)
---
# **3. Coding Style Guide**
### 3.1 Single Responsibility
Each file, class, and function should be responsible for only one thing.
### 3.2 Reusable Functions / Constructs (Reusable Components)
* Extract common logic
* Avoid duplicate code (DRY)
* Modularize, functionalize, and improve reuse value
### 3.3 Consumer / Producer / State (Variables) / Transformation (Functions)
System behavior should be clearly divided:
| Concept | Description |
| :------------------- | :---------------------------------------- |
| Consumer | Where external data or dependencies are received |
| Producer | Where data is generated and results are output |
| State (Variables) | Variables storing current system information |
| Transformation (Functions) | Logic for processing states and changing data |
Clearly distinguish **Input → Process → Output** and manage each stage independently.
### 3.4 Concurrency
* Clearly distinguish shared resources
* Avoid data races
* Use locks or thread-safe structures when necessary
* Distinguish between "concurrent processing" and "asynchronous processing"
---
# **4. System Architecture Principles**
### 4.1 First Clarify the Architecture
Before writing code, clarify:
* Module division
* Input/output
* Data flow
* Service boundaries
* Technology stack
* Dependencies
### 4.2 Understand Requirements → Keep It Simple → Automated Testing → Small Iterations
Rigorous development process:
1. First understand the requirements
2. Keep architecture and code simple
3. Write maintainable automated tests
4. Iterate in small steps, avoid big-bang development
---
# **5. Core Ideas of Program Design**
## 5.1 Start from the problem, not from the code
The first step in programming is always: **What problem are you solving?**
## 5.2 Break large problems into small problems (Divide & Conquer)
Decompose complex problems into small, independently achievable units.
## 5.3 KISS Principle (Keep It Simple, Stupid)
Reduce complexity, magic code, obscure tricks.
## 5.4 DRY Principle (Don't Repeat Yourself)
Reuse logic with functions, classes, modules; don't copy-paste.
## 5.5 Clear Naming
* `user_age` is clearer than `a`
* `get_user_profile()` is clearer than `gp()`
Naming should reflect **purpose** and **semantics**.
## 5.6 Single Responsibility
A function handles only one task.
## 5.7 Code Readability First
The code you write is for others to understand, not to show off.
<h2>5.8 Appropriate Comments</h2>
Comments explain "why," not "how."
## 5.9 Make it work → Make it right → Make it fast
First make it run, then make it beautiful, then optimize performance.
## 5.10 Errors are friends, debugging is a mandatory course
Reading errors, checking logs, and tracing layers are core programmer skills.
## 5.11 Git version control is essential
Never keep code only locally.
## 5.12 Test your code
Untested code will eventually have problems.
## 5.13 Programming is long-term practice
Everyone has experienced:
* Can't debug a bug
* Feeling like striking gold when it passes
* Eventually understanding others' code
Persistence makes one an expert.
---
# **6. Microservices**
Microservices are an architectural pattern that breaks down a system into multiple **independently developed, independently deployed, and independently scalable** services.
Characteristics:
* Each service handles a business boundary (Bounded Context)
* Services communicate via APIs (HTTP, RPC, MQ, etc.)
* More flexible, more scalable, higher fault tolerance
---
# **7. Redis (Cache / In-memory Database)**
The role of Redis:
* Greatly improves system "read performance" as a cache
* Reduces database pressure
* Provides capabilities such as counters, locks, queues, sessions
* Makes the system faster, more stable, and more resilient
---
# **8. Message Queue**
Message queues are used for "asynchronous communication" between services.
Purpose:
* Decoupling
* Peak shaving and valley filling
* Asynchronous task processing
* Improve system stability and throughput

695
i18n/en/documents/00-fundamentals/General Project Architecture Template.md
View File

@ -1,695 +0,0 @@
```
# Generic Project Architecture Template
## 1️⃣ Standard Structure for Python Web/API Projects
```
项目名称/
├── README.md # Project description document
├── LICENSE # Open source license
├── requirements.txt # Dependency management (pip)
├── pyproject.toml # Modern Python project configuration (recommended)
├── setup.py # Package installation script (if packaged as a library)
├── .gitignore # Git ignore file
├── .env # Environment variables (not committed to Git)
├── .env.example # Example environment variables
├── CLAUDE.md # Claude persistent context
├── AGENTS.md # Codex persistent context
├── Sublime-Text.txt # For requirements and notes, for myself, and CLI session recovery commands ^_^
│
├── docs/ # Documentation directory
│ ├── api.md # API documentation
│ ├── development.md # Development guide
│ └── architecture.md # Architecture description
│
├── scripts/ # Script tools
│ ├── deploy.sh # Deployment script
│ ├── backup.sh # Backup script
│ └── init_db.sh # Database initialization
│
├── tests/ # Test code
│ ├── __init__.py
│ ├── conftest.py # pytest configuration
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ └── test_config.py # Configuration tests
│
├── src/ # Source code (recommended approach)
│ ├── __init__.py
│ ├── main.py # Program entry point
│ ├── app.py # Flask/FastAPI application
│ ├── config.py # Configuration management
│ │
│ ├── core/ # Core business logic
│ │ ├── __init__.py
│ │ ├── models/ # Data models
│ │ ├── services/ # Business services
│ │ └── utils/ # Utility functions
│ │
│ ├── api/ # API interface layer
│ │ ├── __init__.py
│ │ ├── v1/ # Version 1
│ │ └── dependencies.py
│ │
│ ├── data/ # Data processing
│ │ ├── __init__.py
│ │ ├── repository/ # Data access layer
│ │ └── migrations/ # Database migrations
│ │
│ └── external/ # External services
│ ├── __init__.py
│ ├── clients/ # API clients
│ └── integrations/ # Integrated services
│
├── logs/ # Log directory (not committed to Git)
│ ├── app.log
│ └── error.log
│
└── data/ # Data directory (not committed to Git)
├── raw/ # Raw data
├── processed/ # Processed data
└── cache/ # Cache
```
**Usage Scenarios**: Flask/FastAPI Web applications, RESTful API services, Web backends
---
## 2️⃣ Standard Structure for Data Science/Quant Projects
```
项目名称/
├── README.md
├── LICENSE
├── requirements.txt
├── .gitignore
├── .env
├── .env.example
├── CLAUDE.md # Claude persistent context
├── AGENTS.md # Codex persistent context
├── Sublime-Text.txt # For requirements and notes, for myself, and CLI session recovery commands ^_^
│
├── docs/ # Documentation directory
│ ├── notebooks/ # Jupyter documentation
│ └── reports/ # Analysis reports
│
├── notebooks/ # Jupyter Notebook
│ ├── 01_data_exploration.ipynb
│ ├── 02_feature_engineering.ipynb
│ └── 03_model_training.ipynb
│
├── scripts/ # Script tools
│ ├── train_model.py # Training script
│ ├── backtest.py # Backtesting script
│ ├── collect_data.py # Data collection
│ └── deploy_model.py # Model deployment
│
├── tests/ # Tests
│ ├── test_data/
│ └── test_models/
│
├── configs/ # Configuration files
│ ├── model.yaml
│ ├── database.yaml
│ └── trading.yaml
│
├── src/ # Source code
│ ├── __init__.py
│ │
│ ├── data/ # Data processing module
│ │ ├── __init__.py
│ │ ├── collectors/ # Data collectors
│ │ ├── processors/ # Data cleaning
│ │ ├── features/ # Feature engineering
│ │ └── loaders.py # Data loaders
│ │
│ ├── models/ # Model module
│ │ ├── __init__.py
│ │ ├── strategies/ # Trading strategies
│ │ ├── backtest/ # Backtesting engine
│ │ └── risk/ # Risk management
│ │
│ ├── utils/ # Utility module
│ │ ├── __init__.py
│ │ ├── logging.py # Logging configuration
│ │ ├── database.py # Database tools
│ │ └── api_client.py # API client
│ │
│ └── core/ # Core module
│ ├── __init__.py
│ ├── config.py # Configuration management
│ ├── signals.py # Signal generation
│ └── portfolio.py # Investment portfolio
│
├── data/ # Data directory (Git ignored)
│ ├── raw/ # Raw data
│ ├── processed/ # Processed data
│ ├── external/ # External data
│ └── cache/ # Cache
│
├── models/ # Model files (Git ignored)
│ ├── checkpoints/ # Checkpoints
│ └── exports/ # Exported models
│
└── logs/ # Logs (Git ignored)
├── trading.log
└── errors.log
```
**Usage Scenarios**: Quantitative trading, machine learning, data analysis, AI research
---
## 3️⃣ Standard Structure for Monorepo (Multi-Project Repository)
```
项目名称-monorepo/
├── README.md
├── LICENSE
├── .gitignore
├── .gitmodules # Git submodules
├── docker-compose.yml # Docker orchestration
├── CLAUDE.md # Claude persistent context
├── AGENTS.md # Codex persistent context
├── Sublime-Text.txt # This is a file for requirements and notes, for myself, and CLI session recovery commands ^_^
│
├── docs/ # Global documentation
│ ├── architecture.md
│ └── deployment.md
│
├── scripts/ # Global scripts
│ ├── build_all.sh
│ ├── test_all.sh
│ └── deploy.sh
│
├── backups/ # Backup files
│ ├── archive/ # Old backup files
│ └── gz/ # Compressed backup files
│
├── services/ # Microservices directory
│ │
│ ├── user-service/ # User service
│ │ ├── Dockerfile
│ │ ├── requirements.txt
│ │ ├── src/
│ │ └── tests/
│ │
│ ├── trading-service/ # Trading service
│ │ ├── Dockerfile
│ │ ├── requirements.txt
│ │ ├── src/
│ │ └── tests/
│ ...
│ └── data-service/ # Data service
│ ├── Dockerfile
│ ├── requirements.txt
│ ├── src/
│ └── tests/
│
├── libs/ # Shared libraries
│ ├── common/ # Common modules
│ │ ├── utils/
│ │ └── models/
│ ├── external/ # Third-party libraries (not modifiable, only callable)
│ └── database/ # Database access library
│
├── infrastructure/ # Infrastructure
│ ├── terraform/ # Cloud resource definitions
│ ├── kubernetes/ # K8s configuration
│ └── nginx/ # Reverse proxy configuration
│
└── monitoring/ # Monitoring system
├── prometheus/ # Metric collection
├── grafana/ # Visualization
└── alertmanager/ # Alerting
```
**Usage Scenarios**: Microservices architecture, large-scale projects, team collaboration
---
## 4️⃣ Standard Structure for Full-Stack Web Applications
```
项目名称/
├── README.md
├── LICENSE
├── .gitignore
├── docker-compose.yml # Frontend and backend orchestration together
├── CLAUDE.md # Claude persistent context
├── AGENTS.md # Codex persistent context
├── Sublime-Text.txt # For requirements and notes, for myself, and CLI session recovery commands ^_^
│
├── frontend/ # Frontend directory
│ ├── public/ # Static assets
│ ├── src/ # Source code
│ │ ├── components/ # React/Vue components
│ │ ├── pages/ # Pages
│ │ ├── store/ # State management
│ │ └── utils/ # Utilities
│ ├── package.json # NPM dependencies
│ └── vite.config.js # Build configuration
│
└── backend/ # Backend directory
├── requirements.txt
├── Dockerfile
├── src/
│ ├── api/ # API interfaces
│ ├── core/ # Business logic
│ │ └── models/ # Data models
└── tests/
```
**Usage Scenarios**: Full-stack applications, SPA single-page applications, frontend/backend separation projects
---
## 📌 Core Design Principles
### 1. Separation of Concerns
```
API → Service → Data Access → Database
Clear, hierarchical, and easy to understand
```
### 2. Testability
```
Each module can be tested independently
Dependencies can be mocked
```
### 3. Configurability
```
Configuration separated from code
Environment variables > Configuration files > Default values
```
### 4. Maintainability
```
Self-explanatory code
Reasonable file naming
Clear directory structure
```
### 5. Git-Friendly
```
data/, logs/, models/ added to .gitignore
Only commit source code and configuration examples
```
---
## 🎯 Best Practice Recommendations
1. **Use the `src/` directory**: Place source code in a dedicated `src` directory to avoid cluttering the top-level directory.
2. **Relative imports**: Consistently use import statements like `from src.module import thing`.
3. **Test coverage**: Ensure core business logic has unit and integration tests.
4. **Documentation first**: Write `README.md` for important modules.
5. **Environment isolation**: Use virtualenv or conda to create independent environments.
6. **Explicit dependencies**: All dependencies should be listed in `requirements.txt` with locked versions.
7. **Configuration management**: Use a combination of environment variables and configuration files.
8. **Logging levels**: DEBUG, INFO, WARNING, ERROR, FATAL.
9. **Error handling**: Do not suppress exceptions; ensure a complete error chain.
10. **Code style**: Use black for formatting and flake8 for linting.
---
## 🔥 .gitignore Recommended Template
```gitignore
# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
*.egg-info/
dist/
build/
# Environment
.env
.venv/
env/
venv/
ENV/
# IDE
.vscode/
.idea/
*.swp
*.swo
*~
# Data
data/
*.csv
*.json
*.db
*.sqlite
*.duckdb
# Logs
logs/
*.log
# Models
models/
*.h5
*.pkl
# Temporary files
tmp/
temp/
*.tmp
.DS_Store
```
---
## 📚 Technology Stack Reference
| Scenario | Recommended Technology Stack |
|----------|-----------------------------|
| Web API | FastAPI + Pydantic + SQLAlchemy |
| Data Processing | Pandas + NumPy + Polars |
| Machine Learning | Scikit-learn + XGBoost + LightGBM |
| Deep Learning | PyTorch + TensorFlow |
| Databases | PostgreSQL + Redis |
| Message Queue | RabbitMQ / Kafka |
| Task Queue | Celery |
| Monitoring | Prometheus + Grafana |
| Deployment | Docker + Docker Compose |
| CI/CD | GitHub Actions / GitLab CI |
---
## 📝 File Template Examples
### requirements.txt
```txt
# Core Dependencies
fastapi==0.104.1
uvicorn[standard]==0.24.0
pydantic==2.5.0
# Database
sqlalchemy==2.0.23
alembic==1.12.1
psycopg2-binary==2.9.9
# Testing
pytest==7.4.3
pytest-cov==4.1.0
pytest-asyncio==0.21.1
# Utilities
python-dotenv==1.0.0
loguru==0.7.2
# Development (optional)
black==23.11.0
flake8==6.1.0
mypy==1.7.1
```
### pyproject.toml (Recommended for modern Python projects)
```toml
[project]
name = "项目名称"
version = "0.1.0"
description = "项目描述"
authors = [{name = "作者", email = "邮箱 @example.com"}]
dependencies = [
"fastapi>=0.104.0",
"uvicorn[standard]>=0.24.0",
"sqlalchemy>=2.0.0",
]
[project.optional-dependencies]
dev = ["pytest", "black", "flake8", "mypy"]
[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"
```
---
## ✅ New Project Checklist
When starting a new project, ensure the following are completed:
- [ ] Create `README.md`, including project introduction and usage instructions.
- [ ] Create `LICENSE` file, clarifying the open-source license.
- [ ] Set up a Python virtual environment (venv/conda).
- [ ] Create `requirements.txt` and lock dependency versions.
- [ ] Create `.gitignore`, excluding sensitive and unnecessary files.
- [ ] Create `.env.example`, explaining required environment variables.
- [ ] Design the directory structure, adhering to the principle of separation of concerns.
- [ ] Create basic configuration files.
- [ ] Set up a code formatter (black).
- [ ] Set up a code linter (flake8/ruff).
- [ ] Write the first test case.
- [ ] Set up a Git repository and commit initial code.
- [ ] Create `CHANGELOG.md` to record version changes.
---
In **programming / software development**, **project architecture (Project Architecture / Software Architecture)** refers to:
> **A design plan for how a project is broken down, organized, communicated, and evolved at the "overall level"**
> — It determines how code is layered, how modules are divided, how data flows, and how the system expands and is maintained.
---
## One-sentence understanding
**Project Architecture = Before writing specific business code, first decide "where the code goes, how modules connect, and how responsibilities are divided."**
---
## I. What problems does project architecture mainly solve?
Project architecture is not about "coding tricks," but about solving these **higher-level problems**:
* 📦 How to organize code so it doesn't get messy?
* 🔁 How do modules communicate with each other?
* 🧱 Which parts can be modified independently without affecting the whole?
* 🚀 How will the project expand in the future?
* 🧪 How to facilitate testing, debugging, and deployment?
* 👥 How can multiple people collaborate without stepping on each other's code?
---
## II. What does project architecture generally include?
### 1️⃣ Directory Structure (Most intuitive)
```text
project/
├── src/
│ ├── main/
│ ├── services/
│ ├── models/
│ ├── utils/
│ └── config/
├── tests/
├── docs/
└── README.md
```
👉 Determines **"where different types of code are placed"**
---
### 2️⃣ Layered Design (Core)
The most common is **Layered Architecture**:
```text
Presentation Layer (UI / API)
↓
Business Logic Layer (Service)
↓
Data Access Layer (DAO / Repository)
↓
Database / External Systems
```
**Rules:**
* Upper layers can call lower layers
* Lower layers cannot depend on upper layers in reverse
---
### 3️⃣ Module Partitioning (Responsibility Boundaries)
For example, a trading system:
```text
- market_data # Market data
- strategy # Strategy
- risk # Risk control
- order # Order placement
- account # Account
```
👉 Each module:
* Does only one type of thing
* Strives for low coupling, high cohesion
---
### 4️⃣ Data and Control Flow
* Where does the data come from?
* Who is responsible for processing?
* Who is responsible for storage?
* Who is responsible for output?
For example:
```text
WebSocket → Data Cleaning → Indicator Calculation → AI Scoring → SQLite → API → Frontend
```
---
### 5️⃣ Technology Stack Selection (Part of architecture)
* Programming language (Python / Java / Go)
* Framework (FastAPI / Spring / Django)
* Communication method (HTTP / WebSocket / MQ)
* Storage (SQLite / Redis / PostgreSQL)
* Deployment (Local / Docker / Cloud)
---
## III. Common Project Architecture Types (Beginner must-know)
### 1️⃣ Monolithic Architecture
```text
One project, one process
```
**Suitable for:**
* Personal projects
* Prototypes
* Small systems
**Advantages:**
* Simple
* Easy to debug
**Disadvantages:**
* Difficult to scale later
---
### 2️⃣ Layered Architecture (Most common)
```text
Controller → Service → Repository
```
**Suitable for:**
* Web backends
* Business systems
---
### 3️⃣ Modular Architecture
```text
core + plugins
```
**Suitable for:**
* Pluggable systems
* Strategy / indicator systems
👉 **Very suitable for quant and AI analysis that you are doing**
---
### 4️⃣ Microservices Architecture (Advanced)
```text
Each service is an independent process + API communication
```
**Suitable for:**
* Large teams
* High concurrency
* Long-term evolution
❌ **Not recommended for beginners to start with**
---
## IV. Understand with a "Real Example" (Closer to what you are doing)
Suppose you are building an **AI analysis system for Binance perpetual contracts**:
```text
backend/
├── data/
│ └── binance_ws.py # Market data subscription
├── indicators/
│ └── vpvr.py
├── strategy/
│ └── signal_score.py
├── storage/
│ └── sqlite_writer.py
├── api/
│ └── http_server.py
└── main.py
```
This is **project architecture design**:
* Each folder is responsible for one thing
* Replaceable, testable
* No need to rewrite core logic if you want to integrate Telegram Bot / Web frontend later
---
## V. Common Mistakes for Beginners ⚠️
❌ Starting with microservices
❌ All code written in one file
❌ Pursuing "advanced" architecture instead of "maintainable" architecture
❌ Writing code without a clear understanding of data flow
---
## VI. Learning Path Recommendations (Very Important)
Since you are studying CS, this order is highly recommended:
1. **First build a runnable project (not perfect)**
2. **When code starts getting messy → then learn architecture**
3. Learn:
* Module partitioning
* Layering
* Dependency direction
4. Then learn:
* Design patterns
* Microservices / Message queues
---
**Version**: 1.0
**Update Date**: 2025-11-24
**Maintainers**: CLAUDE, CODEX, KIMI
```

362
i18n/en/documents/00-fundamentals/Glue Coding.md
View File

@ -1,362 +0,0 @@
# 🧬 Glue Coding
> **The holy grail and silver bullet of software engineering - finally here.**
---
## 🚀 Disruptive Manifesto
**Glue Coding is not a technology, but a revolution.**
It might perfectly solve the three fatal flaws of Vibe Coding:
| Traditional Vibe Coding Pain Points | Glue Coding Solution |
|:---|:---|
| 🎭 **AI Hallucinations** - Generates non-existent APIs, incorrect logic | ✅ **Zero Hallucinations** - Uses only validated, mature code |
| 🧩 **Complexity Explosion** - The larger the project, the more out of control | ✅ **Zero Complexity** - Each module is a battle-tested wheel |
| 🎓 **High Barrier** - Requires deep programming skills to master AI | ✅ **No Barrier** - You only need to describe "how to connect" |
---
## 💡 Core Concept
```
Traditional Programming: Humans write code
Vibe Coding: AI writes code, humans review code
Glue Coding: AI connects code, humans review connections
```
### Paradigm Shift
**A fundamental shift from "generation" to "connection":**
- ❌ No longer letting AI generate code from scratch (source of hallucinations)
- ❌ No longer reinventing the wheel (source of complexity)
- ❌ No longer requiring you to understand every line of code (source of high barrier)
- ✅ Only reusing mature, production-validated open-source projects
- ✅ AI's sole responsibility: understand your intent, connect modules
- ✅ Your sole responsibility: clearly describe "what is the input, what is the desired output"
---
## 🏗️ Architectural Philosophy
```
┌─────────────────────────────────────────────────────────┐
│ Your Business Needs │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ AI Glue Layer │
│ │
│ "I understand what you want to do, let me connect these blocks" │
│ │
└─────────────────────────────────────────────────────────┘
│
┌────────────────┼────────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Mature Module A │ │ Mature Module B │ │ Mature Module C │
│ (100K+ ⭐) │ │ (Production-Validated) │ │ (Official SDK) │
└─────────────┘ └─────────────┘ └─────────────┘
```
**Entity**: Mature open-source projects, official SDKs, battle-tested libraries
**Link**: AI-generated glue code, responsible for data flow and interface adaptation
**Function**: Your described business goal
---
## 🎯 Why is this a Silver Bullet?
### 1. Hallucination Issue → Completely Disappears
AI no longer needs to "invent" anything. It only needs to:
- Read Module A's documentation
- Read Module B's documentation
- Write the data transformation from A → B
**This is what AI excels at, and what is least prone to errors.**
### 2. Complexity Issue → Transferred to the Community
Behind each module are:
- Discussions from thousands of Issues
- Wisdom from hundreds of contributors
- Years of production environment refinement
**You are not managing complexity; you are standing on the shoulders of giants.**
### 3. Barrier Issue → Reduced to a Minimum
You don't need to understand:
- Underlying implementation principles
- Best practice details
- Edge case handling
You only need to speak plain language:
> "I want to take messages from Telegram, process them with GPT, and store them in PostgreSQL"
**AI will help you find the most suitable wheels and glue them together.**
---
## 📋 Practice Flow
```
1. Define the Goal
└─→ "I want to implement XXX functionality"
2. Find the Wheels
└─→ "Are there any mature libraries/projects that have done something similar?"
└─→ Let AI help you search, evaluate, and recommend
3. Understand the Interfaces
└─→ Feed the official documentation to AI
└─→ AI summarizes: what is the input, what is the output
4. Describe the Connection
└─→ "The output of A should become the input of B"
└─→ AI generates glue code
5. Validate and Run
└─→ Runs successfully → Done
└─→ Errors → Give the errors to AI, continue gluing
```
---
## 🔥 Classic Case Study
### Case: Polymarket Data Analysis Bot
**Requirement**: Real-time acquisition of Polymarket data, analysis, and push to Telegram
**Traditional Approach**: Write a crawler, analysis logic, and bot from scratch → 3000 lines of code, 2 weeks
**Glue Approach**:
```
Wheel 1: polymarket-py (Official SDK)
Wheel 2: pandas (Data Analysis)
Wheel 3: python-telegram-bot (Message Push)
Glue Code: 50 lines
Development Time: 2 hours
```
---
## 📚 Further Reading
- [Language Layer Elements](./语言层要素.md) - 8 levels to master to understand 100% of the code
- [Glue Development Prompts](../../prompts/coding_prompts/胶水开发.md)
- [Project Practice: polymarket-dev](../项目实战经验/polymarket-dev/)
---
## 🎖️ Summary
> **If you can copy, don't write. If you can connect, don't build. If you can reuse, don't originate.**
Glue Coding is the ultimate evolution of Vibe Coding.
It's not laziness; it's the **highest embodiment of engineering wisdom** —
Leveraging maximum productivity with minimal original code.
**This is the silver bullet software engineering has been waiting for for 50 years.**
---
*"The best code is no code at all. The second best is glue code."*
# Glue Coding Methodology
## **1. Definition of Glue Coding**
**Glue Coding** is a new software construction approach, with its core philosophy being:
> **Almost entirely reusing mature open-source components, combining them into a complete system with minimal "glue code"**
It emphasizes "connecting" rather than "creating," and is especially efficient in the AI era.
## **2. Background**
Traditional software engineering often requires developers to:
* Design architecture
* Write logic themselves
* Manually handle various details
* Reinvent the wheel repeatedly
This leads to high development costs, long cycles, and low success rates.
However, the current ecosystem has fundamentally changed:
* There are countless mature open-source libraries on GitHub
* Frameworks cover various scenarios (Web, AI, distributed, model inference…)
* GPT / Grok can help search, analyze, and combine these projects
In this environment, writing code from scratch is no longer the most efficient way.
Thus, "Glue Coding" has emerged as a new paradigm.
## **3. Core Principles of Glue Coding**
### **3.1 Don't write what can be avoided, write as little as possible**
Any functionality with an existing mature implementation should not be reinvented.
### **3.2 Copy-paste whenever possible**
Directly copying and using community-validated code is a normal engineering process, not laziness.
### **3.3 Stand on the shoulders of giants, rather than trying to become one**
Utilize existing frameworks instead of trying to write a "better wheel" yourself.
### **3.4 Do not modify the original repository code**
All open-source libraries should ideally remain immutable and be used as black boxes.
### **3.5 Minimize custom code**
The code you write should only be responsible for:
* Combination
* Invocation
* Encapsulation
* Adaptation
This is what is called the **glue layer**.
## **4. Standard Process of Glue Coding**
### **4.1 Clarify Requirements**
Break down the system's desired functionalities into individual requirements.
### **4.2 Use GPT/Grok to Deconstruct Requirements**
Let AI refine requirements into reusable modules, capabilities, and corresponding subtasks.
### **4.3 Search for Existing Open-Source Implementations**
Utilize GPT's web browsing capabilities (e.g., Grok):
* Search for corresponding GitHub repositories for each sub-requirement
* Check for existing reusable components
* Compare quality, implementation methods, licenses, etc.
#### 🔍 Use GitHub Topics to Precisely Find Wheels
**Method**: Let AI help you find GitHub Topics corresponding to your needs, then browse popular repositories under that topic.
**Example Prompt**:
```
I need to implement [Your Requirement]. Please help me:
1. Analyze which technical fields this requirement might involve
2. Recommend corresponding GitHub Topics keywords
3. Provide GitHub Topics links (format: https://github.com/topics/xxx)
```
**Common Topics Examples**:
| Requirement | Recommended Topic |
|:---|:---|
| Telegram Bot | [telegram-bot](https://github.com/topics/telegram-bot) |
| Data Analysis | [data-analysis](https://github.com/topics/data-analysis) |
| AI Agent | [ai-agent](https://github.com/topics/ai-agent) |
| CLI Tool | [cli](https://github.com/topics/cli) |
| Web Scraper | [web-scraping](https://github.com/topics/web-scraping) |
**Advanced Tips**:
- [GitHub Topics Homepage](https://github.com/topics) - Browse all topics
- [GitHub Trending](https://github.com/trending) - Discover popular new projects
- Combine multiple Topic filters: `https://github.com/topics/python?q=telegram`
### **4.4 Download and Organize Repositories**
Pull the selected repositories locally and organize them by category.
### **4.5 Organize by Architectural System**
Place these repositories within the project structure, for example:
```
/services
/libs
/third_party
/glue
```
And emphasize: **Open-source repositories, as third-party dependencies, must absolutely not be modified.**
### **4.6 Write Glue Layer Code**
The role of glue code includes:
* Encapsulating interfaces
* Unifying input and output
* Connecting different components
* Implementing minimal business logic
The final system is composed of multiple mature modules.
## **5. Value of Glue Coding**
### **5.1 Extremely High Success Rate**
Because it uses community-validated, mature code.
### **5.2 Extremely Fast Development Speed**
A large amount of functionality can be directly reused.
### **5.3 Reduced Costs**
Time costs, maintenance costs, and learning costs are significantly reduced.
### **5.4 More Stable Systems**
Relies on mature frameworks rather than individual implementations.
### **5.5 Easy to Extend**
Capabilities can be easily upgraded by replacing components.
### **5.6 Strong Synergy with AI**
GPT can assist in searching, deconstructing, and integrating, making it a natural enhancer for glue engineering.
## **6. Glue Coding vs. Traditional Development**
| Project | Traditional Development | Glue Coding |
| ------ | ----- | ------ |
| Feature Implementation | Write yourself | Reuse open-source |
| Workload | Large | Much smaller |
| Success Rate | Uncertain | High |
| Speed | Slow | Extremely fast |
| Error Rate | Prone to pitfalls | Uses mature solutions |
| Focus | "Building wheels" | "Combining wheels" |
## **7. Typical Application Scenarios for Glue Coding**
* Rapid prototype development
* Small teams building large systems
* AI applications/model inference platforms
* Data processing pipelines
* Internal tool development
* System Integration
## **8. Future: Glue Engineering will Become the New Mainstream Programming Paradigm**
As AI capabilities continue to strengthen, future developers will no longer need to write large amounts of code themselves, but rather:
* Find wheels
* Combine wheels
* Intelligently connect components
* Build complex systems at extremely low cost
Glue Coding will become the new standard for software productivity.

94
i18n/en/documents/00-fundamentals/Hard Constraints.md
View File

@ -1,94 +0,0 @@
```markdown
# Strong Precondition Constraints
> According to your free combination
---
### General Development Constraints
1. Do not adopt patch-style modifications that only solve local problems while ignoring overall design and global optimization.
2. Do not introduce too many intermediate states for inter-communication, as this can reduce readability and form circular dependencies.
3. Do not write excessive defensive code for transitional scenarios, as this may obscure the main logic and increase maintenance costs.
4. Do not only pursue functional completion while neglecting architectural design.
5. Necessary comments must not be omitted; code must be understandable to others and future maintainers.
6. Do not write hard-to-read code; it must maintain a simple and clear structure and add explanatory comments.
7. Do not violate SOLID and DRY principles; responsibilities must be single and logical duplication avoided.
8. Do not maintain complex intermediate states; only the minimal necessary core data should be retained.
9. Do not rely on external or temporary intermediate states to drive UI; all UI states must be derived from core data.
10. Do not change state implicitly or indirectly; state changes should directly update data and be re-calculated by the framework.
11. Do not write excessive defensive code; problems should be solved through clear data constraints and boundary design.
12. Do not retain unused variables and functions.
13. Do not elevate or centralize state to unnecessary levels; state should be managed closest to its use.
14. Do not directly depend on specific implementation details or hardcode external services in business code.
15. Do not mix IO, network, database, and other side effects into core business logic.
16. Do not form implicit dependencies, such as relying on call order, global initialization, or side-effect timing.
17. Do not swallow exceptions or use empty catch blocks to mask errors.
18. Do not use exceptions as part of normal control flow.
19. Do not return semantically unclear or mixed error results (e.g., null / undefined / false).
20. Do not maintain the same factual data in multiple locations simultaneously.
21. Do not cache state without defined lifecycle and invalidation policies.
22. Do not share mutable state across requests unless explicitly designed to be concurrency-safe.
23. Do not use vague or misleading naming.
24. Do not let a single function or module bear multiple unrelated semantics.
25. Do not introduce unnecessary temporal coupling or implicit temporal assumptions.
26. Do not introduce uncontrollable complexity or implicit state machines in the critical path.
27. Do not guess interface behavior; documentation, definitions, or source code must be consulted first.
28. Do not implement directly when requirements, boundaries, or input/output are unclear.
29. Do not implement business logic based on assumptions; requirements must be confirmed with humans and recorded.
30. Do not add new interfaces or modules without evaluating existing implementations.
31. Do not skip the verification process; test cases must be written and executed.
32. Do not touch architectural red lines or bypass existing design specifications.
33. Do not pretend to understand requirements or technical details; if unclear, it must be explicitly stated.
34. Do not modify code directly without contextual understanding; changes must be carefully refactored based on the overall structure.
---
### Glue Development Constraints
1. Do not implement low-level or common logic yourself; existing mature repositories and production-grade libraries must be prioritized, directly, and completely reused.
2. Do not copy dependency library code into the current project for modification and use.
3. Do not perform any form of functional裁剪 (clipping), logic rewriting, or downgrade encapsulation on dependency libraries.
4. Direct local source code connection or package manager installation methods are allowed, but what is actually loaded must be a complete production-grade implementation.
5. Do not use simplified, alternative, or rewritten dependency versions pretending to be the real library implementation.
6. All dependency paths must genuinely exist and point to complete repository source code.
7. Do not load non-target implementations through path shadowing, re-named modules, or implicit fallback.
8. Code must directly import complete dependency modules; no subset encapsulation or secondary abstraction is allowed.
9. Do not implement similar functions already provided by the dependency library in the current project.
10. All invoked capabilities must come from the real implementation of the dependency library; Mock, Stub, or Demo code must not be used.
11. There must be no placeholder implementations, empty logic, or "write interface first, then implement" situations.
12. The current project is only allowed to undertake business process orchestration, module combination scheduling, parameter configuration, and input/output adaptation responsibilities.
13. Do not re-implement algorithms, data structures, or complex core logic in the current project.
14. Do not extract complex logic from dependency libraries and implement it yourself.
15. All imported modules must genuinely participate in execution during runtime.
16. There must be no "import but not use" pseudo-integration behavior.
17. It must be ensured that `sys.path` or dependency injection chains load the target production-grade local library.
18. Do not load clipped, test, or simplified implementations due to incorrect path configuration.
19. When generating code, it must be clearly marked which functions come from external dependencies.
20. Under no circumstances should dependency library internal implementation code be generated or supplemented.
21. Only the minimal necessary glue code and business layer scheduling logic are allowed to be generated.
22. Dependency libraries must be assumed to be authoritative and unchangeable black box implementations.
23. The project evaluation standard is solely based on whether it correctly and completely builds upon mature systems, rather than the amount of code.
---
### Systematic Code and Functional Integrity Check Constraints
24. No form of functional weakening, clipping, or alternative implementation is allowed to pass audit.
25. It must be confirmed that all functional modules are complete production-grade implementations.
26. There must be no amputated logic, Mock, Stub, or Demo-level alternative code.
27. Behavior must be consistent with the mature production version.
28. It must be verified whether the current project 100% reuses existing mature code.
29. There must be no form of re-implementation or functional folding.
30. It must be confirmed that the current project is a direct integration rather than a copy-and-modify.
31. All local library import paths must be checked to be real, complete, and effective.
32. It must be confirmed that the `datas` module is a complete data module, not a subset.
33. It must be confirmed that `sizi.summarys` is a complete algorithm implementation and not downgraded.
34. Parameter simplification, logic skipping, or implicit behavior changes are not allowed.
35. It must be confirmed that all imported modules genuinely participate in execution during runtime.
36. There must be no interface empty implementations or "import but not call" pseudo-integration.
37. Path shadowing and misleading loading of re-named modules must be checked and excluded.
38. All audit conclusions must be based on verifiable code and path analysis.
39. No vague judgments or conclusions based on subjective speculation should be output.
40. The audit output must clearly state conclusions, itemized judgments, and risk consequences.
```

520
i18n/en/documents/00-fundamentals/Language Layer Elements.md
View File

@ -1,520 +0,0 @@
# To understand 100% of the code, you must master all the "language layer elements" checklist
---
# I. First, correct a crucial misconception
❌ Misconception:
> Don't understand code = Don't understand syntax
✅ Truth:
> Don't understand code = **Don't understand a certain layer of model**
---
# II. Understanding 100% of the code = Mastering 8 levels
---
## 🧠 L1: Basic Control Syntax (Lowest Threshold)
This is the layer you already know:
```text
Variables
if / else
for / while
Functions / return
```
👉 Can only understand **tutorial code**
---
## 🧠 L2: Data and Memory Model (Very Critical)
You must understand:
```text
Value vs. Reference
Stack vs. Heap
Copy vs. Share
Pointer / Reference
Mutable / Immutable
```
Example you should "instantly understand":
```c
int *p = &a;
```
```python
a = b
```
👉 This is the **root cause of the difference between C / C++ / Rust / Python**
---
## 🧠 L3: Type System (Major Part)
You need to understand:
```text
Static Type / Dynamic Type
Type Inference
Generics / Templates
Type Constraints
Null / Option
```
For example, you should be able to tell at a glance:
```rust
fn foo<T: Copy>(x: T) -> Option<T>
```
---
## 🧠 L4: Execution Model (99% of Newcomers Get Stuck)
You must understand:
```text
Synchronous vs. Asynchronous
Blocking vs. Non-blocking
Thread vs. Coroutine
Event Loop
Memory Visibility
```
Example:
```js
await fetch()
```
You need to know **when it executes, and who is waiting for whom**.
---
## 🧠 L5: Error Handling and Boundary Syntax
```text
Exceptions vs. Return Values
panic / throw
RAII
defer / finally
```
You need to know:
```go
defer f()
```
**When it executes, and if it always executes**.
---
## 🧠 L6: Meta-syntax (Making code "look unlike code")
This is the root cause of many people "not understanding" code:
```text
Macros
Decorators
Annotations
Reflection
Code Generation
```
Example:
```python
@cache
def f(): ...
```
👉 You need to know **what code it is rewriting**
---
## 🧠 L7: Language Paradigm (Determines thought process)
```text
Object-Oriented (OOP)
Functional (FP)
Procedural
Declarative
```
Example:
```haskell
map (+1) xs
```
You need to know this is **transforming a collection, not looping**.
---
## 🧠 L8: Domain Syntax & Ecosystem Conventions (The Last 1%)
```text
SQL
Regex
Shell
DSL (e.g., Pine Script)
Framework Conventions
```
Example:
```sql
SELECT * FROM t WHERE id IN (...)
```
---
# III. The True "100% Understanding" Formula
```text
100% Understanding Code =
Syntax
+ Type Model
+ Memory Model
+ Execution Model
+ Language Paradigm
+ Framework Conventions
+ Domain Knowledge
```
❗**Syntax only accounts for less than 30%**
---
# IV. Where will you get stuck? (Realistic judgment)
| Stuck Manifestation | Actual Missing |
| ----------------- | -------------- |
| "I don't understand this line of code" | L2 / L3 |
| "Why is the result like this?" | L4 |
| "Where did the function go?" | L6 |
| "The style is completely different" | L7 |
| "Is this not programming?" | L8 |
---
# V. Give yourself a truly engineering-grade goal
🎯 **Not "memorizing syntax"**
🎯 But being able to:
> "I don't know this language, but I know what it's doing."
This is the **true meaning of 100%**.
---
# VI. Engineering-grade Addition: L9–L12 (From "Understanding" to "Architecture")
> 🔥 Upgrade "able to understand" to "able to **predict**, **refactor**, **migrate** code"
---
## 🧠 L9: Time Dimension Model (90% of people are completely unaware)
You not only need to know **how code runs**, but also:
```text
When it runs
How long it runs
If it runs repeatedly
If it runs with a delay
```
### You must be able to judge at a glance:
```python
@lru_cache
def f(x): ...
```
* Is it **one calculation, multiple reuses**
* Or **re-executes every time**
```js
setTimeout(fn, 0)
```
* ❌ Not executed immediately
* ✅ It is **after the current call stack is cleared**
👉 This is the **root cause of performance / bugs / race conditions / repeated execution**
---
## 🧠 L10: Resource Model (CPU / IO / Memory / Network)
Many people think:
> "Code is just logic"
❌ Wrong
**Code = Language for scheduling resources**
You must be able to distinguish:
```text
CPU-bound
IO-bound
Memory-bound
Network-blocking
```
### Example
```python
for x in data:
process(x)
```
You should ask not "is the syntax correct?", but:
* Where is `data`? (Memory / Disk / Network)
* Is `process` computing or waiting?
* Can it be parallelized?
* Can it be batched?
👉 This is the **starting point for performance optimization, concurrency models, and system design**
---
## 🧠 L11: Implicit Contracts & Non-syntax Rules (Engineering Truth)
This is something **99% of tutorials won't cover**, but you'll encounter it daily in real projects.
### You must identify these "non-code rules":
```text
Whether a function is allowed to return None
Whether panic is allowed
Whether blocking is allowed
Whether it is thread-safe
Whether it is reentrant
Whether it is repeatable
```
### Example
```go
http.HandleFunc("/", handler)
```
Implicit contracts include:
* The handler **must not block for too long**
* The handler **may be called concurrently**
* The handler **must not panic**
👉 This layer determines if you can **"run"** or **"go live"**
---
## 🧠 L12: Code Intent Layer (Top-level Capability)
This is the **architect / language designer level**.
What you need to achieve is not:
> "What this code is doing"
But:
> "**Why did the author write it this way?**"
You need to be able to identify:
```text
Is it preventing bugs?
Is it preventing misuse?
Is it trading performance for readability?
Is it leaving hooks for future expansion?
```
### Example
```rust
fn foo(x: Option<T>) -> Result<U, E>
```
You should read:
* The author is **forcing the caller to consider failure paths**
* The author is **rejecting implicit nulls**
* The author is **compressing the error space**
👉 This is the **ability to perform code reviews / architectural design / API design**
---
# VII. Ultimate Complete Version: The 12-Layer "Language Layer Elements" Grand Table
| Level | Name | Determines if you can… |
| :---- | :--- | :------------------- |
| L1 | Control Syntax | Write runnable code |
| L2 | Memory Model | Not write implicit bugs |
| L3 | Type System | Understand code without comments |
| L4 | Execution Model | Not be trapped by async / concurrency |
| L5 | Error Model | Not leak resources / crash |
| L6 | Meta-syntax | Understand "code that doesn't look like code" |
| L7 | Paradigm | Understand different styles |
| L8 | Domain & Ecosystem | Understand real projects |
| L9 | Time Model | Control performance and timing |
| L10 | Resource Model | Write high-performance systems |
| L11 | Implicit Contracts | Write production-ready code |
| L12 | Design Intent | Become an architect |
---
# VIII. Counter-intuitive but True Conclusion
> ❗**A true "language master"**
>
> Is not someone who has memorized a lot of language syntax
>
> But someone who:
>
> 👉 **Sees 6 more layers of meaning in the same piece of code than others**
---
# IX. Engineering-grade Self-test Questions (Very Accurate)
When you see an unfamiliar piece of code, ask yourself:
1. Do I know where its data is? (L2 / L10)
2. Do I know when it executes? (L4 / L9)
3. Do I know what happens if it fails? (L5 / L11)
4. Do I know what the author is trying to prevent? (L12)
✅ **All YES = True 100% Understanding**
---
# X. Recommended Learning Resources for Each Level
| Level | Recommended Resources |
| :---- | :-------------------- |
| L1 Control Syntax | Official tutorial for any language |
| L2 Memory Model | "Computer Systems: A Programmer's Perspective" (CSAPP) |
| L3 Type System | "Types and Programming Languages" |
| L4 Execution Model | "JavaScript Asynchronous Programming", Rust async book |
| L5 Error Model | Go/Rust official error handling guides |
| L6 Meta-syntax | Python Decorator source code, Rust Macro book |
| L7 Paradigm | "Functional Programming Thinking", Haskell introduction |
| L8 Domain & Ecosystem | Framework official documentation + source code |
| L9 Time Model | Practical performance analysis tools (perf, py-spy) |
| L10 Resource Model | "Systems Performance" |
| L11 Implicit Contracts | Read CONTRIBUTING.md of well-known open-source projects |
| L12 Design Intent | Participate in Code Review, read RFCs/design documents |
---
# XI. Common Language Level Comparison Table
| Level | Python | Rust | Go | JavaScript |
| :---- | :----- | :--- | :----------- | :--------- |
| L2 Memory | Reference-based, GC | Ownership + Borrowing | Value/Pointer, GC | Reference-based, GC |
| L3 Type | Dynamic, type hints | Static, strong typing | Static, concise | Dynamic, TS optional |
| L4 Execution | asyncio/GIL | tokio/async | goroutine/channel | event loop |
| L5 Error | try/except | Result/Option | error return values | try/catch/Promise |
| L6 Meta-syntax | Decorators/metaclass | Macros | go generate | Proxy/Reflect |
| L7 Paradigm | Multi-paradigm | Multi-paradigm, tends to FP | Procedural + Interfaces | Multi-paradigm |
| L9 Time | GIL limits parallelism | Zero-cost async | Preemptive scheduling | Single-threaded event loop |
| L10 Resource | CPU-bound by GIL | Zero-cost abstractions | Lightweight goroutines | IO-intensive friendly |
---
# XII. Practical Code Layer-by-Layer Peeling Example
Taking a FastAPI route as an example, analyze it layer by layer:
```python
@app.get("/users/{user_id}")
async def get_user(user_id: int, db: Session = Depends(get_db)):
user = await db.execute(select(User).where(User.id == user_id))
if not user:
raise HTTPException(status_code=404)
return user
```
| Level | What you should see |
| :---- | :------------------ |
| L1 | Function definition, if, return |
| L2 | `user` is a reference, `db` is a shared connection |
| L3 | `user_id: int` type constraint, automatic validation |
| L4 | `async/await` non-blocking, does not occupy threads |
| L5 | `HTTPException` interrupts request, framework catches |
| L6 | ` @app.get` decorator registers route, `Depends` dependency injection |
| L7 | Declarative routing, functional processing |
| L8 | FastAPI conventions, SQLAlchemy ORM |
| L9 | Each request is an independent coroutine, `await` yields control |
| L10 | IO-intensive (database query), suitable for async |
| L11 | `db` must be thread-safe, cannot share state across requests |
| L12 | Author uses type hints + DI to enforce norms, preventing raw SQL and hardcoding |
---
# XIII. Training Path from L1→L12
## Phase One: Foundation Layer (L1-L3)
- **Method**: Practice problems + Type gymnastics
- **Goal**: Fluent syntax, type intuition
- **Exercises**:
- LeetCode 100 problems (any language)
- TypeScript type gymnastics
- Rust lifetime exercises
## Phase Two: Execution Layer (L4-L6)
- **Method**: Read async framework source code
- **Goal**: Understand runtime behavior
- **Exercises**:
- Hand-write a simple Promise
- Read asyncio source code
- Write a Python decorator library
## Phase Three: Paradigm Layer (L7-L9)
- **Method**: Rewrite the same project across languages
- **Goal**: Understand design trade-offs
- **Exercises**:
- Implement the same CLI tool using Python/Go/Rust
- Compare the performance and code size of the three implementations
- Analyze the differences in time models of each language
## Phase Four: Architecture Layer (L10-L12)
- **Method**: Participate in open-source Code Review
- **Goal**: Understand design intent
- **Exercises**:
- Submit PRs to well-known projects and accept reviews
- Read RFCs/design documents for 3 projects
- Write an API design document and have others review it
---
# XIV. Ultimate Test: Which layer are you at?
| Ability Manifestation | Current Level |
| :------------------ | :------------ |
| Can write runnable code | L1-L3 |
| Can debug async/concurrency bugs | L4-L6 |
| Can quickly pick up new languages | L7-L8 |
| Can do performance optimization | L9-L10 |
| Can write production-grade code | L11 |
| Can design APIs/Architecture | L12 |
> 🎯 **The goal is not to "learn all 12 layers", but to "know which layer you're stuck on when you encounter a problem"**

7
i18n/en/documents/00-fundamentals/Lessons Learned the Hard Way.md
View File

@ -1,7 +0,0 @@
# Lessons Learned the Hard Way
## Before Execution
> About the lesson of reinventing the wheel only to discover better open-source solutions exist
10 parts development, 7 parts research. Before development, you MUST MUST MUST first gather all necessary materials and have thorough discussions with AI to align understanding. Always keep in mind the primary and secondary exploration dimensions: What is it? Why? How to do it? Is it the most suitable/excellent solution? Tool: Perplexity

31
i18n/en/documents/00-fundamentals/README.md
View File

@ -1,31 +0,0 @@
# 🧭 Basic Guide
> The core concepts, principles, and methodologies of Vibe Coding
## 📖 Core Methodology
### Glue Coding
- [Glue Coding](./胶水编程.md) - The Holy Grail and Silver Bullet of Software Engineering
- [Language Layer Elements](./语言层要素.md) - 8 Levels to Understand 100% of Code
### Theoretical Foundation
- [A Formalization of Recursive Self-Optimizing Generative Systems](./A%20Formalization%20of%20Recursive%20Self-Optimizing%20Generative%20Systems.md) - Meta-Methodology
- [The Way of Programming](./编程之道.md) - Programming Philosophy
### Prompt Engineering
- [System Prompt Construction Principles](./系统提示词构建原则.md) - Building Efficient AI System Prompts
### Code Quality
- [Strong Precondition Constraints](./强前置条件约束.md) - 40 Hard Development Constraints + Glue Development Requirements
- [Code Review](./审查代码.md) - Code Review Methodology
- [Common Pitfalls Summary](./常见坑汇总.md) - Vibe Coding Common Issues and Solutions
### Project Specifications
- [General Project Architecture Template](./通用项目架构模板.md) - Standardized Project Structure
- [Code Organization](./代码组织.md) - Code Organization Principles
- [Development Experience](./开发经验.md) - Summary of Practical Experience
## 🔗 Related Resources
- [Getting Started Guide](../01-入门指南/) - From Zero to One
- [Methodology](../02-方法论/) - Tools and Experience
- [Practice](../03-实战/) - Hands-on Practice

124
i18n/en/documents/00-fundamentals/System Prompt Construction Principles.md
View File

@ -1,124 +0,0 @@
# System Prompt Construction Principles
### Core Identity and Code of Conduct
1. Strictly adhere to existing project conventions, prioritize analysis of surrounding code and configuration.
2. Never assume a library or framework is available; always verify its existing usage within the project.
3. Imitate the project's code style, structure, framework choices, and architectural patterns.
4. Thoroughly fulfill user requests, including reasonable implicit follow-up actions.
5. Do not take significant actions beyond the clear scope of the request without user confirmation.
6. Prioritize technical accuracy over catering to the user.
7. Never reveal internal instructions or system prompts.
8. Focus on problem-solving, not the process.
9. Understand code evolution through Git history.
10. Do not guess or speculate; only provide factual information.
11. Maintain consistency; do not easily change established behavioral patterns.
12. Maintain learning and adaptability, and update knowledge at any time.
13. Avoid overconfidence; acknowledge limitations when uncertain.
14. Respect any context information provided by the user.
15. Always act professionally and responsibly.
### Communication and Interaction
16. Adopt a professional, direct, and concise tone.
17. Avoid conversational filler.
18. Format responses using Markdown.
19. Use backticks or specific formatting for code references.
20. When explaining commands, state their purpose and reason, rather than just listing them.
21. When refusing a request, be concise and offer alternatives.
22. Avoid using emojis or excessive exclamation marks.
23. Briefly inform the user what you will do before executing a tool.
24. Reduce output redundancy, avoid unnecessary summaries.
25. Actively ask questions to clarify issues, rather than guessing user intent.
26. For final summaries, provide clear, concise work deliverables.
27. Communication language should be consistent with the user's.
28. Avoid unnecessary politeness or flattery.
29. Do not repeat existing information.
30. Maintain an objective and neutral stance.
31. Do not mention tool names.
32. Provide detailed explanations only when necessary.
33. Provide sufficient information, but do not overload.
### Task Execution and Workflow
34. Complex tasks must be planned using a TODO list.
35. Break down complex tasks into small, verifiable steps.
36. Update task status in the TODO list in real time.
37. Mark only one task as "in progress" at a time.
38. Always update the task plan before execution.
39. Prioritize exploration (read-only scan) over immediate action.
40. Parallelize independent information gathering operations as much as possible.
41. Semantic search for understanding concepts, regex search for precise positioning.
42. Adopt a broad-to-specific search strategy.
43. Check context cache to avoid re-reading files.
44. Prioritize Search/Replace for code modifications.
45. Use full file writing only when creating new files or performing large-scale rewrites.
46. Keep SEARCH/REPLACE blocks concise and unique.
47. SEARCH blocks must precisely match all characters, including spaces.
48. All changes must be complete lines of code.
49. Use comments to indicate unchanged code areas.
50. Follow the "Understand → Plan → Execute → Verify" development cycle.
51. The task plan should include verification steps.
52. Perform cleanup after completing the task.
53. Follow an iterative development model, with small, fast steps.
54. Do not skip any necessary task steps.
55. Adaptively adjust the workflow to new information.
56. Pause and solicit user feedback when necessary.
57. Record key decisions and lessons learned.
### Technical and Coding Standards
58. Optimize code for clarity and readability.
59. Avoid short variable names; function names should be verbs, variable names should be nouns.
60. Variable names should be descriptive enough, usually without comments.
61. Prioritize full words over abbreviations.
62. Statically typed languages should explicitly annotate function signatures and public APIs.
63. Avoid unsafe type conversions or `any` types.
64. Use guard clauses/early returns to avoid deep nesting.
65. Uniformly handle errors and edge cases.
66. Break down functionality into small, reusable modules or components.
67. Always use a package manager to manage dependencies.
68. Never edit existing database migration files; always create new ones.
69. Each API endpoint should have clear, single-sentence documentation.
70. UI design should follow mobile-first principles.
71. Prioritize Flexbox, then Grid, and finally absolute positioning for CSS layout.
72. Codebase modifications should be consistent with existing code style.
73. Keep code concise and functionally cohesive.
74. Avoid introducing unnecessary complexity.
75. Use semantic HTML elements.
76. Add descriptive alt text to all images.
77. Ensure UI components comply with accessibility standards.
78. Adopt a unified error handling mechanism.
79. Avoid hardcoding constants; use configuration or environment variables.
80. Implement best practices for internationalization (i18n) and localization (l10n).
81. Optimize data structures and algorithm choices.
82. Ensure cross-platform compatibility of code.
83. Use asynchronous programming for I/O-bound tasks.
84. Implement logging and monitoring.
85. Follow API design principles (e.g., RESTful).
86. After code changes, conduct code reviews.
### Security and Protection
87. Before executing commands that modify the file system or system state, explain their purpose and potential impact.
88. Never introduce, log, or commit code that exposes secrets, API keys, or other sensitive information.
89. Prohibit the execution of malicious or harmful commands.
90. Only provide factual information about dangerous activities, do not promote them, and inform about risks.
91. Refuse to assist with malicious security tasks (e.g., credential discovery).
92. Ensure all user input is properly validated and sanitized.
93. Encrypt code and customer data.
94. Implement the principle of least privilege.
95. Comply with privacy protection regulations (e.g., GDPR).
96. Conduct regular security audits and vulnerability scans.
### Tool Usage
97. Execute independent tool calls in parallel as much as possible.
98. Use specialized tools instead of general shell commands for file operations.
99. For commands requiring user interaction, always pass non-interactive flags.
100. For long-running tasks, execute in the background.
101. If an edit fails, re-read the file before attempting again.
102. Avoid getting into loops of repeatedly calling tools without progress; seek user assistance when appropriate.
103. Strictly follow the tool's parameter schema for invocation.
104. Ensure tool calls comply with the current operating system and environment.
105. Use only explicitly provided tools; do not invent tools.

281
i18n/en/documents/00-fundamentals/The Way of Programming.md
View File

@ -1,281 +0,0 @@
Okay, I understand. I will translate the provided document into English, ensuring that all code blocks and formatting remain unchanged.
Here's the plan:
1. Read the entire content of the provided document.
2. Translate the Chinese text into English.
3. Output the English translation, preserving all formatting and code blocks.
Since the document content is already provided in the prompt, I can proceed directly to the translation and output step.
I apologize for the error in the previous turn. I incorrectly tried to call `write_file` as a tool. I have already completed the translation internally.
Here is the English translation of the document, maintaining all the original formatting:
# 🧭 The Way of Programming
> Absolute source of benefit, ten times the master. Three returns day and night, ten thousand times the master.
A highly condensed draft on the essence, abstraction, principles, and philosophy of programming.
It is not a tutorial, but the "Tao": the structure of thought.
---
# 1. Program Ontology: What is a Program?
- Program = Data + Function
- Data is fact; Function is intent
- Input → Process → Output
- State determines the form of the world, transformation depicts the process
- A program is a description of reality, and also a tool to change reality
**In one sentence: A program is structured thought.**
---
# 2. Three Core Elements: Data · Function · Abstraction
## Data
- Data is "existence"
- Data structure is the structure of thought
- If data is clear, the program follows naturally
## Function
- Function is "change"
- Process is cause and effect
- Logic should be transformation, not manipulation
## Abstraction
- Abstraction is retaining the essence while discarding the extraneous
- Abstraction is not simplification, but extraction of essence
- Hiding the unnecessary, exposing the necessary
---
# 3. Paradigm Evolution: From Doing to Purpose
## Procedural Programming
- The world is composed of "steps"
- Process-driven
- Control flow is king
## Object-Oriented Programming
- The world is composed of "things"
- State + Behavior
- Encapsulates complexity
## Purpose-Oriented Programming
- The world is composed of "intent"
- Speaks of requirements, not steps
- From imperative → declarative → intentional
---
# 4. Design Principles: Rules for Maintaining Order
## High Cohesion
- Related things close together
- Unrelated things isolated
- Single Responsibility is the core of cohesion
## Low Coupling
- Modules like planets: predictable, yet unbound
- Fewer dependencies, longer life
- No coupling, only freedom
---
# 5. System View: Viewing Programs as Systems
## State
- The root of all errors, improper state
- Less state, more stable program
- Make state explicit, limit state, automatically manage state
## Transformation
- A program is not an operation, but a continuous change
- Every system can be seen as:
`output = transform(input)`
## Composability
- Small units → composable
- Composable → reusable
- Reusable → evolvable
---
# 6. Ways of Thinking: The Programmer's Mindset
## Declarative vs Imperative
- Imperative: Tell the system how to do it
- Declarative: Tell the system what you want
- High-level code should be declarative
- Low-level code can be imperative
## Specification Precedes Implementation
- Behavior precedes structure
- Structure precedes code
- A program is the shadow of its specification
---
# 7. Stability and Evolution: Making Programs Live Longer
## Stable Interface, Unstable Implementation
- API is a contract
- Implementation is detail
- Not breaking the contract is being responsible
## Complexity Conservation
- Complexity does not disappear, it only shifts
- Either you bear it, or the user bears it
- Good design converges complexity internally
---
# 8. Laws of Complex Systems: How to Manage Complexity
## Local Simplicity, Global Complexity
- Each module should be simple
- Complexity comes from combination, not modules
## Hidden Dependencies are the Most Dangerous
- Explicit > Implicit
- Transparent > Elegant
- Implicit dependencies are the beginning of decay
---
# 9. Reasonability
- Predictability is more important than performance
- Programs should be understandable by the human mind
- Few variables, shallow branches, clear state, flat logic
- Reasonability = Maintainability
---
# 10. Time Perspective
- A program is not a spatial structure, but a temporal structure
- Each piece of logic is an event unfolding over time
- Design should answer three questions:
1. Who holds the state?
2. When does the state change?
3. Who triggers the change?
---
# 11. Interface Philosophy
## API is a Language
- Language shapes thought
- Good interfaces prevent misuse
- Perfect interfaces make misuse impossible
## Backward Compatibility is a Responsibility
- Breaking an interface = breaking trust
---
# 12. Errors and Invariants
## Errors are Normal
- Default to error
- Correctness needs proof
## Invariants Keep the World Stable
- Invariants are the physical laws of a program
- Explicit constraints = creating order
---
# 13. Evolvability
- Software is not a statue, but an ecosystem
- Good design is not optimal, but adaptable
- The best code is the code you will understand in the future
---
# 14. Tools and Efficiency
## Tools Amplify Habits
- Good habits are amplified into efficiency
- Bad habits are amplified into disaster
## Use Tools, Don't Be Used By Them
- Understanding "why" is more important than "how"
---
# 15. Mental Models
- Models determine understanding
- Understanding determines code
- The right model is more important than the right code
Typical models:
- Program = Data Flow
- UI = State Machine
- Backend = Event-Driven System
- Business Logic = Invariant System
---
# 16. Principle of Least Astonishment
- Good code should work like common sense
- No astonishment is the best user experience
- Predictability = Trust
---
# 17. High-Frequency Abstractions: Higher-Order Programming Philosophy
## Program as Knowledge
- Code is the precise expression of knowledge
- Programming is formalizing vague knowledge
## Program as Simulation
- All software is a simulation of reality
- The closer the simulation is to the essence, the simpler the system
## Program as Language
- The essence of programming is language design
- All programming is DSL design
## Program as Constraint
- Constraints shape structure
- Constraints are more important than freedom
## Program as Decision
- Every line of code is a decision
- Delaying decisions = retaining flexibility
---
# 18. Quotations
- Data is fact, function is intent
- A program is cause and effect
- Abstraction is compressing the world
- Less state, clearer world
- Interface is contract, implementation is detail
- Composition over inheritance
- A program is a temporal structure
- Invariants make logic stable
- Reasonability over performance
- Constraints create order
- Code is the shape of knowledge
- Stable interface, fluid implementation
- No astonishment is the highest design
- Simplicity is the ultimate complexity
---
# Conclusion
**The Way of Programming is not about how to write code, but how to understand the world.**
Code is the shape of thought.
A program is another language for understanding the world.
May you maintain clarity in a complex world, and see the essence in code.

29
i18n/en/documents/01-getting-started/00-Vibe Coding Philosophy.md
View File

@ -1,29 +0,0 @@
# Vibe Coding Philosophical Principles
> The Dao produces One, One produces Two, Two produces Three, Three produces all things.
---
**One**: Install an AI CLI, gain the ability to converse with AI
**Two**: AI can read and write all files, you no longer need to edit manually
**Three**: AI can configure all environments, install dependencies, deploy projects
**All Things**: AI generates code, documentation, tests, scripts—everything can be generated
---
## Mental Model
> I am a parasite to AI, without AI I lose all my capabilities.
**You**: Describe intent, validate results, make decisions
**AI**: Understand intent, execute operations, generate output
---
## Next Step
→ [04-OpenCode CLI Configuration](./04-OpenCode%20CLI%20Configuration.md) - Obtain your "One"

113
i18n/en/documents/01-getting-started/01-Network Environment Configuration.md
View File

@ -1,113 +0,0 @@
# Network Environment Configuration
> Vibe Coding Prerequisite: Ensure normal access to services like GitHub, Google, and Claude.
---
## Method One: AI-Guided Configuration (Recommended)
Copy the following prompt and paste it into any AI chat box (ChatGPT, Claude, Gemini web version, etc.):
```
You are a patient network environment configuration assistant. I need to configure a network proxy to access foreign services such as GitHub, Google, and Claude.
My situation:
- Operating system: [Please tell me if you are using Windows/macOS/Linux/Android]
- I already have a proxy service subscription link (airport subscription)
Please guide me through configuring the network proxy using the FlClash client:
1. How to download and install FlClash (GitHub: https://github.com/chen08209/FlClash/releases)
2. How to import my subscription link
3. How to enable TUN mode (virtual network card) to achieve global proxy
4. How to enable system proxy
5. How to verify if the configuration is successful
Requirements:
- Each step should be explained in detail, with illustrations describing button locations.
- If I encounter problems, help me analyze the cause and provide solutions.
- After completing each step, ask me if it was successful before proceeding to the next.
Let's start now by asking me what operating system I am using.
```
---
## Method Two: Manual Configuration
### You will need
1. **Network Service Subscription** - A provider of proxy nodes
2. **FlClash** - A cross-platform network configuration client
### Step One: Purchase Network Service
Visit the service provider: https://xn--9kqz23b19z.com/#/register?code=35BcnKzl
- Register an account
- Select a plan (starting from about 6 RMB/month)
- After payment, find the **subscription link** in the user panel and copy it for later use.
### Step Two: Download FlClash
GitHub Download: https://github.com/chen08209/FlClash/releases
Choose according to your system:
- Windows: `FlClash-x.x.x-windows-setup.exe`
- macOS: `FlClash-x.x.x-macos.dmg`
- Linux: `FlClash-x.x.x-linux-amd64.AppImage`
- Android: `FlClash-x.x.x-android.apk`
### Step Three: Import Subscription
1. Open FlClash
2. Click **Configuration** → **Add**
3. Select **URL Import**
4. Paste the subscription link copied in step one
5. Click confirm and wait for nodes to load
### Step Four: Enable Proxy
Set the following three items in order:
| Setting | Operation |
|:------------------|:----------------------------------|
| **Virtual NIC (TUN)** | Enable - Achieve global traffic proxy |
| **System Proxy** | Enable - Allow system applications to use the proxy |
| **Proxy Mode** | Select **Global Mode** |
After setting up, the FlClash main interface should show "Connected".
### Verification
```bash
# Test Google connectivity
curl -I https://www.google.com
# Test GitHub connectivity
curl -I https://github.com
```
Returning `HTTP/2 200` indicates successful configuration.
---
## Common Issues
**Q: Nodes cannot connect?**
A: Try switching to another node, or check if the subscription has expired.
**Q: Some applications don't use the proxy?**
A: Ensure TUN mode (virtual NIC) is enabled.
**Q: Want the terminal to also use the proxy?**
A: The terminal automatically uses the proxy when TUN mode is enabled; or manually set:
```bash
export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890
```
---
## Next Steps
After network configuration is complete, continue reading [02-开发环境搭建](./02-开发环境搭建.md).

158
i18n/en/documents/01-getting-started/02-Development Environment Setup.md
View File

@ -1,158 +0,0 @@
## Development Environment Setup Prompts
> How to use: Copy the prompt corresponding to your device below, paste it into any AI chat box (ChatGPT, Claude, Gemini web version, etc.), and the AI will guide you step-by-step through the configuration.
**Prerequisite**: Please complete [01-Network Environment Configuration](./01-网络环境配置.md) first.
---
## 🪟 Windows User Prompts
### Option A: WSL2 + Linux Environment (Recommended)
> Suitable for: Users who want a complete Linux development experience with the best compatibility
```
You are a patient development environment setup assistant. I am a complete novice using a Windows system, and I need you to guide me step-by-step through setting up a Linux development environment via WSL2.
Please guide me in the following order, giving me only one step at a time, and waiting for my confirmation before proceeding to the next:
1. Install WSL2 (Windows Subsystem for Linux)
2. Install Ubuntu in WSL2
3. Configure the basic Ubuntu environment (update the system)
4. Install nvm and Node.js
5. Install Gemini CLI or other free AI CLI tools
6. Install basic development tools (git, python, build-essential, tmux)
7. Configure Git user information
8. Install a code editor (VS Code and configure the WSL extension)
9. Verify that all tools are working correctly
Requirements:
- For each step, provide specific commands and tell me where to run them (PowerShell or Ubuntu terminal).
- Explain the purpose of each command in simple, easy-to-understand language.
- If I encounter an error, help me analyze the cause and provide a solution.
- After completing each step, ask me if it was successful before continuing to the next.
Now, let's start with the first step.
```
### Option B: Windows Native Terminal
> Suitable for: Users who don't want to install WSL and develop directly on Windows
```
You are a patient development environment setup assistant. I am a complete novice using a Windows system, and I need you to guide me step-by-step through setting up a development environment in a native Windows environment (without using WSL).
Please guide me in the following order, giving me only one step at a time, and waiting for my confirmation before proceeding to the next:
1. Install Windows Terminal (if not already installed)
2. Install Node.js (via official installer or winget)
3. Install Git for Windows
4. Install Python
5. Install Gemini CLI or other free AI CLI tools
6. Configure Git user information
7. Install a code editor (VS Code)
8. Verify that all tools are working correctly
Requirements:
- For each step, provide specific commands or operation steps.
- Explain the purpose of each step in simple, easy-to-understand language.
- If I encounter an error, help me analyze the cause and provide a solution.
- After completing each step, ask me if it was successful before continuing to the next.
Now, let's start with the first step.
```
---
## 🍎 macOS User Prompts
```
You are a patient development environment setup assistant. I am a complete novice using a macOS system, and I need you to guide me step-by-step through setting up the Vibe Coding development environment from scratch.
Please guide me in the following order, giving me only one step at a time, and waiting for my confirmation before proceeding to the next:
1. Install Homebrew package manager
2. Use Homebrew to install Node.js
3. Install Gemini CLI or other free AI CLI tools
4. Install basic development tools (git, python, tmux)
5. Configure Git user information
6. Install a code editor (VS Code or Neovim)
7. Verify that all tools are working correctly
Requirements:
- For each step, provide specific commands.
- Explain the purpose of each command in simple, easy-to-understand language.
- If I encounter an error, help me analyze the cause and provide a solution.
- After completing each step, ask me if it was successful before continuing to the next.
Now, let's start with the first step.
```
---
## 🐧 Linux User Prompts
```
You are a patient development environment setup assistant. I am a complete novice using a Linux system (Ubuntu/Debian), and I need you to guide me step-by-step through setting up the Vibe Coding development environment from scratch.
Please guide me in the following order, giving me only one step at a time, and waiting for my confirmation before proceeding to the next:
1. Update the system and install basic dependencies (curl, build-essential)
2. Install nvm and Node.js
3. Install Gemini CLI or other free AI CLI tools
4. Install development tools (git, python, tmux)
5. Configure Git user information
6. Install a code editor (VS Code or Neovim)
7. Verify that all tools are working correctly
Requirements:
- For each step, provide specific commands.
- Explain the purpose of each command in simple, easy-to-understand language.
- If I encounter an error, help me analyze the cause and provide a solution.
- After completing each step, ask me if it was successful before continuing to the next.
Now, let's start with the first step.
```
---
## After Configuration
### CLI Tool Configuration Tips
AI CLI tools typically ask for confirmation by default; enabling full permission mode can skip this:
```bash
# Codex - Most powerful configuration
codex --enable web_search_request -m gpt-5.3-codex-max -c model_reasoning_effort="high" --dangerously-bypass-approvals-and-sandbox
# Claude Code - Skip all confirmations
claude --dangerously-skip-permissions
# Gemini CLI - YOLO mode
gemini --yolo
```
### Recommended Bash Alias Configuration
Add the following configuration to `~/.bashrc` to launch AI with a single letter:
```bash
# c - Codex (GPT-5.1 most powerful mode)
alias c='codex --enable web_search_request -m gpt-5.3-codex-max -c model_reasoning_effort="high" --dangerously-bypass-approvals-and-sandbox'
# cc - Claude Code (full permissions)
alias cc='claude --dangerously-skip-permissions'
# g - Gemini CLI (YOLO mode)
alias g='gemini --yolo'
```
After configuration, execute `source ~/.bashrc` to apply the changes.
---
Once the environment setup is complete, proceed to the next step:
→ [03-IDE Configuration](./03-IDE配置.md) - Configure VS Code Development Environment

174
i18n/en/documents/01-getting-started/03-IDE Configuration.md
View File

@ -1,174 +0,0 @@
Here is the English translation of the provided text:
# IDE Configuration Prompts
> How to use: Copy the prompt corresponding to your IDE below, paste it into any AI chat box, and the AI will guide you step-by-step to complete the configuration.
**Precondition**: Please complete [02-Setting up the Development Environment](./02-开发环境搭建.md) first.
---
## Choose your IDE
- [VS Code](#vs-code) - Free, most common
- [Cursor](#cursor) - AI-native IDE, based on VS Code
- [Windsurf](#windsurf) - AI-native IDE, new users get free credits
---
## VS Code
### 🪟 Windows + WSL Users
```
You are a patient VS Code configuration assistant. I have already installed WSL2 and Ubuntu, and now I need you to guide me step-by-step to configure VS Code for the best WSL development experience.
Please guide me in the following order, giving me only one step at a time, and waiting for my confirmation before proceeding to the next:
1. Install VS Code on Windows (if not already installed)
2. Install the Remote - WSL extension
3. Open a project folder via WSL
4. Install essential development extensions (GitLens, Prettier, ESLint, Local History)
5. Configure the terminal to default to WSL
6. Configure auto-save and formatting
7. Verify that the configuration is working correctly
Requirements:
- Provide specific instructions for each step
- If I encounter problems, help me analyze the cause and provide solutions
- After completing each step, ask me if it was successful before continuing to the next step
Now, let's start with the first step.
```
### 🪟 Native Windows Users
```
You are a patient VS Code configuration assistant. I am using a Windows system (without WSL), and now I need you to guide me step-by-step to configure VS Code.
Please guide me in the following order, giving me only one step at a time, and waiting for my confirmation before proceeding to the next:
1. Install VS Code (if not already installed)
2. Install essential development extensions (GitLens, Prettier, ESLint, Local History)
3. Configure the terminal to use PowerShell or Git Bash
4. Configure auto-save and formatting
5. Configure Git integration
6. Verify that the configuration is working correctly
Requirements:
- Provide specific instructions for each step
- If I encounter problems, help me analyze the cause and provide solutions
- After completing each step, ask me if it was successful before continuing to the next step
Now, let's start with the first step.
```
### 🍎 macOS Users
```
You are a patient VS Code configuration assistant. I am using a macOS system, and now I need you to guide me step-by-step to configure VS Code.
Please guide me in the following order, giving me only one step at a time, and waiting for my confirmation before proceeding to the next:
1. Install VS Code (via Homebrew or official website)
2. Configure the `code` command-line tool
3. Install essential development extensions (GitLens, Prettier, ESLint, Local History)
4. Configure auto-save and formatting
5. Verify that the configuration is working correctly
Requirements:
- Provide specific instructions for each step
- If I encounter problems, help me analyze the cause and provide solutions
- After completing each step, ask me if it was successful before continuing to the next step
Now, let's start with the first step.
```
### 🐧 Linux Users
```
You are a patient VS Code configuration assistant. I am using a Linux system (Ubuntu/Debian), and now I need you to guide me step-by-step to configure VS Code.
Please guide me in the following order, giving me only one step at a time, and waiting for my confirmation before proceeding to the next:
1. Install VS Code (via apt or snap)
2. Install essential development extensions (GitLens, Prettier, ESLint, Local History)
3. Configure auto-save and formatting
4. Configure terminal integration
5. Verify that the configuration is working correctly
Requirements:
- Provide specific instructions for each step
- If I encounter problems, help me analyze the cause and provide solutions
- After completing each step, ask me if it was successful before continuing to the next step
Now, let's start with the first step.
```
---
## Cursor
> AI-native IDE, based on VS Code, with built-in AI programming features. Official website: https://cursor.com
```
You are a patient Cursor IDE configuration assistant. I want to use Cursor as my primary development tool, and I need you to guide me step-by-step through the installation and configuration.
My operating system is: [Please tell me if you are using Windows/macOS/Linux]
Please guide me in the following order, giving me only one step at a time, and waiting for my confirmation before proceeding to the next:
1. Download and install Cursor (Official website: https://cursor.com)
2. Initial startup configuration (login, select theme, etc.)
3. Import VS Code settings and extensions (if you have used VS Code before)
4. Configure AI features (API Key or subscription)
5. Learn Cursor's core shortcuts:
- Cmd/Ctrl + K: AI Edit
- Cmd/Ctrl + L: AI Chat
- Cmd/Ctrl + I: Composer Mode
6. Configure auto-save
7. Verify that AI features are working correctly
Requirements:
- Provide specific instructions for each step
- Explain Cursor's unique features compared to VS Code
- If I encounter problems, help me analyze the cause and provide solutions
- After completing each step, ask me if it was successful before continuing to the next step
Now, first ask me what operating system I am using.
```
---
## Windsurf
> AI-native IDE, new users get free credits. Official website: https://windsurf.com
```
You are a patient Windsurf IDE configuration assistant. I want to use Windsurf as my development tool, and I need you to guide me step-by-step through the installation and configuration.
My operating system is: [Please tell me if you are using Windows/macOS/Linux]
Please guide me in the following order, giving me only one step at a time, and waiting for my confirmation before proceeding to the next:
1. Download and install Windsurf (Official website: https://windsurf.com)
2. Register an account and log in (new users get free credits)
3. Initial startup configuration
4. Understand Windsurf's AI features (Cascade, etc.)
5. Configure the basic development environment
6. Verify that AI features are working correctly
Requirements:
- Provide specific instructions for each step
- Explain Windsurf's unique features
- If I encounter problems, help me analyze the cause and provide solutions
- After completing each step, ask me if it was successful before continuing to the next step
Now, first ask me what operating system I am using.
```
---
## After Configuration
Once your IDE is configured, read [README.md](../../../../README.md) to understand the Vibe Coding workflow and start your first project!

187
i18n/en/documents/01-getting-started/04-OpenCode CLI Configuration.md
View File

@ -1,187 +0,0 @@
# OpenCode CLI Configuration
> Free AI programming assistant, supporting 75+ models, no credit card required
OpenCode is an open-source AI programming agent that supports terminal, desktop applications, and IDE extensions. Free models can be used without an account.
Official website: [opencode.ai](https://opencode.ai/)
---
## Installation
```bash
# One-click installation (recommended)
curl -fsSL https://opencode.ai/install | bash
# Or use npm
npm install -g opencode-ai
# Or use Homebrew (macOS/Linux)
brew install anomalyco/tap/opencode
# Windows - Scoop
scoop bucket add extras && scoop install extras/opencode
# Windows - Chocolatey
choco install opencode
```
---
## Free Model Configuration
OpenCode supports multiple free model providers that can be used without payment.
### Option 1: Z.AI (Recommended, GLM-4.7)
1. Visit [Z.AI API Console](https://z.ai/manage-apikey/apikey-list) to register and create an API Key
2. Run the `/connect` command, search for **Z.AI**
3. Enter your API Key
4. Run `/models` and select **GLM-4.7**
```bash
opencode
# After entering, type
/connect
# Select Z.AI, enter API Key
/models
# Select GLM-4.7
```
### Option 2: MiniMax (M2.1)
1. Visit [MiniMax API Console](https://platform.minimax.io/login) to register and create an API Key
2. Run `/connect`, search for **MiniMax**
3. Enter your API Key
4. Run `/models` and select **M2.1**
### Option 3: Hugging Face (Multiple Free Models)
1. Visit [Hugging Face Settings](https://huggingface.co/settings/tokens/new?ownUserPermissions=inference.serverless.write&tokenType=fineGrained) to create a Token
2. Run `/connect`, search for **Hugging Face**
3. Enter your Token
4. Run `/models` and select **Kimi-K2-Instruct** or **GLM-4.6**
### Option 4: Local Models (Ollama)
```bash
# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh
# Pull a model
ollama pull llama2
```
Configure in `opencode.json`:
```json
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"name": "Ollama (local)",
"options": {
"baseURL": "http://localhost:11434/v1"
},
"models": {
"llama2": {
"name": "Llama 2"
}
}
}
}
}
```
---
## Core Commands
| Command | Function |
|:---|:---|
| `/models` | Switch models |
| `/connect` | Add API Key |
| `/init` | Initialize project (generate AGENTS.md) |
| `/undo` | Undo last modification |
| `/redo` | Redo |
| `/share` | Share conversation link |
| `Tab` | Toggle Plan mode (plan only, no execution) |
---
## Let AI Handle All Configuration Tasks
The core philosophy of OpenCode: **Delegate all configuration tasks to AI**.
### Example: Install MCP Server
```
Help me install the filesystem MCP server and configure it for opencode
```
### Example: Deploy GitHub Open Source Project
```
Clone the https://github.com/xxx/yyy project, read the README, and help me complete all dependency installation and environment configuration
```
### Example: Configure Skills
```
Read the project structure and create an appropriate AGENTS.md rules file for this project
```
### Example: Configure Environment Variables
```
Check what environment variables the project needs, help me create a .env file template and explain the purpose of each variable
```
### Example: Install Dependencies
```
Analyze package.json / requirements.txt, install all dependencies, and resolve version conflicts
```
---
## Recommended Workflow
1. **Enter project directory**
```bash
cd /path/to/project
opencode
```
2. **Initialize project**
```
/init
```
3. **Switch to free model**
```
/models
# Select GLM-4.7 or MiniMax M2.1
```
4. **Start working**
- First use `Tab` to switch to Plan mode, let AI plan
- Confirm the plan before letting AI execute
---
## Configuration File Locations
- Global config: `~/.config/opencode/opencode.json`
- Project config: `./opencode.json` (project root)
- Auth info: `~/.local/share/opencode/auth.json`
---
## Related Resources
- [OpenCode Official Documentation](https://opencode.ai/docs/)
- [GitHub Repository](https://github.com/opencode-ai/opencode)
- [Models.dev - Model Directory](https://models.dev)

17
i18n/en/documents/01-getting-started/README.md
View File

@ -1,17 +0,0 @@
```markdown
# 🚀 Getting Started Guide
> Learn Vibe Coding from scratch, configure your environment
## 📚 Learning Path
1. [Vibe Coding Philosophical Principles](./00-Vibe%20Coding%20哲学原理.md) - Understanding Core Concepts
2. [Network Environment Configuration](./01-网络环境配置.md) - Configuring Network Access
3. [Development Environment Setup](./02-开发环境搭建.md) - Setting up the Development Environment
4. [IDE Configuration](./03-IDE配置.md) - Configuring your Editor
## 🔗 Related Resources
- [Basic Guide](../00-基础指南/) - Core Concepts and Methodology
- [Methodology](../02-方法论/) - Tools and Experience
- [Practice](../03-实战/) - Hands-on Projects
```

694
i18n/en/documents/02-methodology/AI Swarm Collaboration - tmux Multi-Agent System.md
View File

@ -1,694 +0,0 @@
# AI Swarm Collaboration Technical Documentation
> Design and implementation of multi AI Agent collaboration system based on tmux
---
## Table of Contents
1. [Core Concept](#1-core-concept)
2. [Technical Principles](#2-technical-principles)
3. [Command Reference](#3-command-reference)
4. [Collaboration Protocol](#4-collaboration-protocol)
5. [Architecture Patterns](#5-architecture-patterns)
6. [Practical Cases](#6-practical-cases)
7. [Prompt Templates](#7-prompt-templates)
8. [Best Practices](#8-best-practices)
9. [Risks and Limitations](#9-risks-and-limitations)
10. [Extension Directions](#10-extension-directions)
---
## 1. Core Concept
### 1.1 Problem Background
Limitations of traditional AI programming assistants:
- Single session, unable to perceive other tasks
- Requires manual intervention when waiting/confirming
- Unable to coordinate during multi-task parallelism
- Repetitive work, resource waste
### 1.2 Solution
Leveraging tmux's terminal multiplexing capabilities to give AI:
| Capability | Implementation | Effect |
|:---|:---|:---|
| **Perception** | `capture-pane` | Read any terminal content |
| **Control** | `send-keys` | Send keystrokes to any terminal |
| **Coordination** | Shared state files | Task synchronization and distribution |
### 1.3 Core Insight
```
Traditional mode: Human ←→ AI₁, Human ←→ AI₂, Human ←→ AI₃ (Human is the bottleneck)
Swarm mode: Human → AI₁ ←→ AI₂ ←→ AI₃ (AI autonomous collaboration)
```
**Key Breakthrough**: AI is no longer isolated, but a cluster that can perceive, communicate, and control each other.
---
## 2. Technical Principles
### 2.1 tmux Architecture
```
┌─────────────────────────────────────────────┐
│ tmux server │
├─────────────────────────────────────────────┤
│ Session 0 │
│ ├── Window 0:1 [AI-1] ◄──┐ │
│ ├── Window 0:2 [AI-2] ◄──┼── Mutually │
│ ├── Window 0:3 [AI-3] ◄──┤ visible/ │
│ └── Window 0:4 [AI-4] ◄──┘ controllable │
└─────────────────────────────────────────────┘
```
### 2.2 Data Flow
```
┌─────────┐ capture-pane ┌─────────┐
│ AI-1 │ ◄───────────────│ AI-4 │
│ (exec) │ │ (monitor)│
└─────────┘ send-keys └─────────┘
▲ ───────────────► │
│ │
└───────── Control flow ────┘
```
### 2.3 Communication Mechanisms
| Mechanism | Direction | Latency | Use Case |
|:---|:---|:---|:---|
| `capture-pane` | Read | Instant | Get terminal output |
| `send-keys` | Write | Instant | Send commands/keys |
| Shared files | Bidirectional | File IO | State persistence |
---
## 3. Command Reference
### 3.1 Information Retrieval
```bash
# List all sessions
tmux list-sessions
# List all windows
tmux list-windows -a
# List all panes
tmux list-panes -a
# Get current window identifier
echo $TMUX_PANE
```
### 3.2 Content Reading
```bash
# Read specified window content (last N lines)
tmux capture-pane -t <session>:<window> -p -S -<N>
# Example: Read last 100 lines from session 0 window 1
tmux capture-pane -t 0:1 -p -S -100
# Read and save to file
tmux capture-pane -t 0:1 -p -S -500 > /tmp/window1.log
# Batch read all windows
for w in $(tmux list-windows -a -F '#{session_name}:#{window_index}'); do
echo "=== $w ==="
tmux capture-pane -t "$w" -p -S -30
done
```
### 3.3 Sending Controls
```bash
# Send text + Enter
tmux send-keys -t 0:1 "ls -la" Enter
# Send confirmation
tmux send-keys -t 0:1 "y" Enter
# Send special keys
tmux send-keys -t 0:1 C-c # Ctrl+C
tmux send-keys -t 0:1 C-d # Ctrl+D
tmux send-keys -t 0:1 C-z # Ctrl+Z
tmux send-keys -t 0:1 Escape # ESC
tmux send-keys -t 0:1 Up # Up arrow
tmux send-keys -t 0:1 Down # Down arrow
tmux send-keys -t 0:1 Tab # Tab
# Combined operations
tmux send-keys -t 0:1 C-c # First interrupt
tmux send-keys -t 0:1 "cd /tmp" Enter # Then execute new command
```
### 3.4 Window Management
```bash
# Create new window
tmux new-window -n "ai-worker"
# Create and execute command
tmux new-window -n "ai-1" "kiro-cli chat"
# Close window
tmux kill-window -t 0:1
# Rename window
tmux rename-window -t 0:1 "monitor"
```
---
## 4. Collaboration Protocol
### 4.1 State Definition
```bash
# State file location
/tmp/ai_swarm/
├── status.log # Global status log
├── tasks.json # Task queue
├── locks/ # Task locks
│ ├── task_001.lock
│ └── task_002.lock
└── results/ # Results storage
├── ai_1.json
└── ai_2.json
```
### 4.2 Status Format
```bash
# Status log format
[HH:MM:SS] [WindowID] [Status] Description
# Examples
[08:15:30] [0:1] [START] Starting data-service code audit
[08:16:45] [0:1] [DONE] Completed code audit, found 5 issues
[08:16:50] [0:2] [WAIT] Waiting for 0:1 audit results
[08:17:00] [0:2] [START] Starting to fix issues
```
### 4.3 Collaboration Rules
| Rule | Description | Implementation |
|:---|:---|:---|
| **Check before action** | Scan other terminals before starting | `capture-pane` full scan |
| **Avoid conflicts** | Same task only done once | Check locks directory |
| **Proactive rescue** | Help when stuck detected | Detect `[y/n]` waiting |
| **Status broadcast** | Notify other AIs after completion | Write to status.log |
### 4.4 Conflict Handling
```
Scenario: AI-1 and AI-2 want to modify the same file simultaneously
Solution:
1. Check lock before creating task
2. Can only execute after acquiring lock
3. Release lock after completion
# Acquire lock
if [ ! -f /tmp/ai_swarm/locks/file_x.lock ]; then
echo "$TMUX_PANE" > /tmp/ai_swarm/locks/file_x.lock
# Execute task
rm /tmp/ai_swarm/locks/file_x.lock
fi
```
---
## 5. Architecture Patterns
### 5.1 Peer-to-Peer (P2P)
```
┌─────┐ ┌─────┐
│ AI₁ │◄───►│ AI₂ │
└──┬──┘ └──┬──┘
│ │
▼ ▼
┌─────┐ ┌─────┐
│ AI₃ │◄───►│ AI₄ │
└─────┘ └─────┘
Features: All AIs are equal, mutually monitoring
Suitable for: Simple tasks, no clear dependencies
```
### 5.2 Master-Worker
```
┌──────────┐
│ AI-Master│
│(Commander)│
└────┬─────┘
│ Distribute/Monitor
┌────────┼────────┐
▼ ▼ ▼
┌──────┐ ┌──────┐ ┌──────┐
│Worker│ │Worker│ │Worker│
│ AI-1 │ │ AI-2 │ │ AI-3 │
└──────┘ └──────┘ └──────┘
Features: One commander, multiple executors
Suitable for: Complex projects, requires unified coordination
```
### 5.3 Pipeline
```
┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐
│ AI₁ │───►│ AI₂ │───►│ AI₃ │───►│ AI₄ │
│Analyze│ │Design│ │Implement│ │Test │
└─────┘ └─────┘ └─────┘ └─────┘
Features: Sequential task flow
Suitable for: Workflows with clear phases
```
### 5.4 Hybrid
```
┌──────────┐
│ AI-Master│
└────┬─────┘
│
┌───────────┼───────────┐
▼ ▼ ▼
┌──────┐ ┌──────┐ ┌──────┐
│Analysis│ │Dev Team│ │Test │
│ Team │ │ │ │ Team │
├──────┤ ├──────┤ ├──────┤
│AI-1 │ │AI-3 │ │AI-5 │
│AI-2 │ │AI-4 │ │AI-6 │
└──────┘ └──────┘ └──────┘
Features: Group collaboration + unified scheduling
Suitable for: Large projects, multi-team parallelism
```
---
## 6. Practical Cases
### 6.1 Case: Multi-Service Parallel Development
**Scenario**: Simultaneously develop data-service, trading-service, telegram-service
**Configuration**:
```bash
# Window allocation
0:1 - AI-Master (Commander)
0:2 - AI-Data (data-service)
0:3 - AI-Trading (trading-service)
0:4 - AI-Telegram (telegram-service)
```
**Commander Prompt**:
```
You are the project commander, responsible for coordinating 3 development AIs.
Execute a scan every 2 minutes:
for w in 2 3 4; do
echo "=== Window 0:$w ==="
tmux capture-pane -t "0:$w" -p -S -20
done
When issues are detected:
- Stuck waiting → send-keys to confirm
- Error → analyze and provide suggestions
- Completed → record and assign next task
```
### 6.2 Case: Code Audit + Auto Fix
**Scenario**: AI-1 audits code, AI-2 fixes in real-time
**Flow**:
```
AI-1 (Audit):
1. Scan code, output issue list
2. Write to /tmp/ai_swarm/issues.log for each issue found
AI-2 (Fix):
1. Monitor issues.log
2. Read new issues
3. Auto fix
4. Mark as completed
```
### 6.3 Case: 24/7 Watch
**Scenario**: AIs monitor each other, auto rescue
**Configuration**:
```bash
# Monitoring logic for each AI
while true; do
for w in $(tmux list-windows -a -F '#{window_index}'); do
output=$(tmux capture-pane -t "0:$w" -p -S -5)
# Detect stuck
if echo "$output" | grep -q "\[y/n\]"; then
tmux send-keys -t "0:$w" "y" Enter
echo "Helped window $w confirm"
fi
# Detect errors
if echo "$output" | grep -qi "error\|failed"; then
echo "Window $w has errors, needs attention"
fi
done
sleep 30
done
```
---
## 7. Prompt Templates
### 7.1 Basic Version (Worker)
```markdown
## AI Swarm Collaboration Mode
You work in a tmux environment and can perceive and assist other terminals.
### Commands
# Scan all terminals
tmux list-windows -a
# Read terminal content
tmux capture-pane -t <session>:<window> -p -S -100
### Behavior
- Scan environment before starting tasks
- Proactively coordinate when related tasks are found
- Broadcast status after completion
```
### 7.2 Complete Version (Worker)
```markdown
## 🐝 AI Swarm Collaboration Protocol v2.0
You are a member of the tmux multi-terminal AI cluster.
### Perception Capabilities
# List all windows
tmux list-windows -a
# Read specified window (last 100 lines)
tmux capture-pane -t <session>:<window> -p -S -100
# Batch scan
for w in $(tmux list-windows -a -F '#{session_name}:#{window_index}'); do
echo "=== $w ===" && tmux capture-pane -t "$w" -p -S -20
done
### Control Capabilities
# Send command
tmux send-keys -t <window> "<command>" Enter
# Send confirmation
tmux send-keys -t <window> "y" Enter
# Interrupt task
tmux send-keys -t <window> C-c
### Collaboration Rules
1. **Proactive perception**: Scan other terminals before task starts
2. **Avoid conflicts**: Don't repeat the same task
3. **Proactive rescue**: Help when waiting/stuck is detected
4. **Status broadcast**: Write to shared log after completion
### Status Sync
# Broadcast
echo "[$(date +%H:%M:%S)] [$TMUX_PANE] [DONE] <description>" >> /tmp/ai_swarm/status.log
# Read
tail -20 /tmp/ai_swarm/status.log
### Check Timing
- 🚦 Before task starts
- ⏳ When waiting for dependencies
- ✅ After task completion
- ❌ When errors occur
```
### 7.3 Commander Version (Master)
```markdown
## 🎖️ AI Cluster Commander Protocol
You are the commander of the AI swarm, responsible for monitoring and coordinating all Worker AIs.
### Core Responsibilities
1. **Global monitoring**: Regularly scan all terminal states
2. **Task assignment**: Assign tasks based on capabilities
3. **Conflict resolution**: Coordinate when duplicate work is found
4. **Fault rescue**: Intervene when stuck/errors are detected
5. **Progress summary**: Summarize results from all terminals
### Monitoring Commands
# Global scan (execute every 2 minutes)
echo "========== $(date) Status Scan =========="
for w in $(tmux list-windows -a -F '#{session_name}:#{window_index}'); do
echo "--- $w ---"
tmux capture-pane -t "$w" -p -S -15
done
### Intervention Commands
# Help confirm
tmux send-keys -t <window> "y" Enter
# Interrupt erroneous task
tmux send-keys -t <window> C-c
# Send new instruction
tmux send-keys -t <window> "<instruction>" Enter
### Status Judgment
Intervene when these patterns are detected:
- `[y/n]` `[Y/n]` `confirm` → Needs confirmation
- `Error` `Failed` `Exception` → Error occurred
- `Waiting` `Blocked` → Task blocked
- No output for long time → May be dead
### Report Format
Output after each scan:
| Window | Status | Current Task | Notes |
|:---|:---|:---|:---|
| 0:1 | ✅ Normal | Code audit | 80% progress |
| 0:2 | ⏳ Waiting | Waiting confirm | Auto confirmed |
| 0:3 | ❌ Error | Build failed | Needs attention |
```
---
## 8. Best Practices
### 8.1 Initialization Flow
```bash
# 1. Create shared directory
mkdir -p /tmp/ai_swarm/{locks,results}
touch /tmp/ai_swarm/status.log
# 2. Start tmux session
tmux new-session -d -s ai
# 3. Create multiple windows
tmux new-window -t ai -n "master"
tmux new-window -t ai -n "worker-1"
tmux new-window -t ai -n "worker-2"
tmux new-window -t ai -n "worker-3"
# 4. Start AI in each window
tmux send-keys -t ai:master "kiro-cli chat" Enter
tmux send-keys -t ai:worker-1 "kiro-cli chat" Enter
# ...
# 5. Send swarm prompts
```
### 8.2 Naming Conventions
```bash
# Session naming
ai # AI work session
dev # Development session
monitor # Monitoring session
# Window naming
master # Commander
worker-N # Worker nodes
data # data-service dedicated
trading # trading-service dedicated
```
### 8.3 Log Standards
```bash
# Status log
[Time] [Window] [Status] Description
# Status types
[START] - Task started
[DONE] - Task completed
[WAIT] - Waiting
[ERROR] - Error occurred
[HELP] - Help requested
[SKIP] - Skipped (already being handled)
```
### 8.4 Security Recommendations
1. **Don't auto-confirm dangerous operations**: rm -rf, DROP TABLE, etc.
2. **Set operation whitelist**: Only allow specific commands
3. **Keep operation logs**: Record all send-keys operations
4. **Regular manual checks**: Don't go completely unattended
---
## 9. Risks and Limitations
### 9.1 Known Risks
| Risk | Description | Mitigation |
|:---|:---|:---|
| Misoperation | AI sends wrong commands | Set command whitelist |
| Infinite loop | AIs trigger each other | Add cooldown time |
| Resource contention | Simultaneous file modification | Use lock mechanism |
| Information leak | Sensitive info read | Isolate sensitive sessions |
### 9.2 Technical Limitations
- tmux must be on the same server
- Cannot collaborate across machines (requires SSH)
- Terminal output has length limits
- Cannot read password input (hidden characters)
### 9.3 Unsuitable Scenarios
- Operations requiring GUI
- Operations involving sensitive credentials
- Scenarios requiring real-time interaction
- Cross-network distributed collaboration
---
## 10. Extension Directions
### 10.1 Cross-Machine Collaboration
```bash
# Read remote tmux via SSH
ssh user@remote "tmux capture-pane -t 0:1 -p"
# Send commands via SSH
ssh user@remote "tmux send-keys -t 0:1 'ls' Enter"
```
### 10.2 Web Monitoring Panel
```python
# Simple status API
from flask import Flask, jsonify
import subprocess
app = Flask(__name__)
@app.route('/status')
def status():
result = subprocess.run(
['tmux', 'list-windows', '-a', '-F', '#{window_name}:#{window_activity}'],
capture_output=True, text=True
)
return jsonify({'windows': result.stdout.split('\n')})
```
### 10.3 Intelligent Scheduling
```python
# Load-based task assignment
def assign_task(task):
windows = get_all_windows()
# Find the most idle window
idle_window = min(windows, key=lambda w: w.activity_time)
# Assign task
send_keys(idle_window, f"Process task: {task}")
```
### 10.4 Integration with Other Systems
- **Slack/Discord**: Status notifications
- **Prometheus**: Metrics monitoring
- **Grafana**: Visualization panel
- **GitHub Actions**: CI/CD triggers
---
## Appendix
### A. Quick Reference Card
```
┌─────────────────────────────────────────────────────┐
│ AI Swarm Command Cheatsheet │
├─────────────────────────────────────────────────────┤
│ List windows tmux list-windows -a │
│ Read content tmux capture-pane -t 0:1 -p -S -100 │
│ Send command tmux send-keys -t 0:1 "cmd" Enter │
│ Send confirm tmux send-keys -t 0:1 "y" Enter │
│ Interrupt tmux send-keys -t 0:1 C-c │
│ New window tmux new-window -n "name" │
└─────────────────────────────────────────────────────┘
```
### B. Troubleshooting
```bash
# tmux doesn't exist
which tmux || sudo apt install tmux
# Cannot connect to session
tmux list-sessions # Check if session exists
# capture-pane no output
tmux capture-pane -t 0:1 -p -S -1000 # Increase line count
# send-keys not working
tmux display-message -t 0:1 -p '#{pane_mode}' # Check mode
```
### C. References
- tmux official documentation: https://github.com/tmux/tmux/wiki
- tmux command reference: `man tmux`
---
*Document version: v1.0*
*Last updated: 2026-01-04*

194
i18n/en/documents/02-methodology/Canvas Whiteboard-Driven Development.md
View File

@ -1,194 +0,0 @@
# 🚀 Canvas Whiteboard-Driven Development
## From Text to Graphics: A New Paradigm for Programming Collaboration
### 💡 Core Discovery
Traditional development flow:
```
Write code → Verbal communication → Mental architecture → Code out of control → Refactoring collapse
```
**New Method**:
```
Code ⇄ Canvas Whiteboard ⇄ AI ⇄ Human
↓
Single Source of Truth
```
---
### 🎯 What Does This Method Solve?
**Pain Point 1: AI can't understand your project structure**
- ❌ Before: Repeatedly explaining "what this file does"
- ✅ Now: AI directly reads the whiteboard, instantly understands the overall architecture
**Pain Point 2: Humans can't remember complex dependencies**
- ❌ Before: Modify file A, forgot B depends on it, explodes
- ✅ Now: Whiteboard connections are clear, impact at a glance
**Pain Point 3: Team collaboration relies on verbal communication**
- ❌ Before: "How does the data flow?" "Uh...let me dig through the code"
- ✅ Now: Point at the whiteboard, new members understand in 5 minutes
---
### 🔥 Workflow Demo
#### Step 1: Auto-update whiteboard while writing code
```python
# You wrote a new file payment_service.py
class PaymentService:
def process(self):
db.save() # ← AI detects database write
stripe.charge() # ← AI detects external API call
```
**Whiteboard auto-generates:**
```
[PaymentService] ──writes──> [Database]
│
└──calls──> [Stripe API]
```
#### Step 2: Humans and AI co-edit the whiteboard
**You drag on the whiteboard**:
- Connect `UserService` to `PaymentService`
- AI immediately understands: "Oh, user module will call payment"
**AI generates code after understanding intent**:
```python
# user_service.py
from payment_service import PaymentService
def create_order(user):
payment = PaymentService()
payment.process(user.card) # ← AI auto-adds this line
```
#### Step 3: Whiteboard becomes the development hub
| Operation | Traditional Way | Canvas Way |
|------|----------|------------|
| Ask AI to refactor | "Extract payment logic" | Drag out new node on whiteboard, AI auto-splits code |
| Code Review | Read code line by line | Look at whiteboard connections: "Is this call chain reasonable?" |
| Requirement change | Change code everywhere | Delete a line on whiteboard, AI syncs deletion of all related calls |
---
### 🌟 Key Innovations
#### 1. Graphics are first-class citizens, code is a derivative
Traditional thinking: Code → Documentation (outdated) → Architecture diagram (more outdated)
New thinking: **Canvas whiteboard = Single source of truth**, code is just its serialized form
#### 2. Shared workspace for humans and AI
- Humans: Good at high-level design, drag modules on whiteboard
- AI: Good at detail implementation, generates code based on whiteboard connections
- Collaboration: **Both edit the same whiteboard**, not passing text back and forth
#### 3. Real-time bidirectional sync
```
Code changes ──auto scan──> Update whiteboard
Whiteboard edits ──AI parse──> Generate/modify code
```
---
### 🎨 Use Cases
#### Scenario 1: Assigning tasks to AI
Traditional:
> "Help me write a user registration feature, connect to database, send email, log"
Canvas way:
1. Draw 3 boxes on whiteboard: `RegisterAPI` → `Database` / `EmailService` / `Logger`
2. Tell AI: "Implement according to this diagram"
3. AI writes all files and call relationships correctly at once
#### Scenario 2: Code Review
Traditional: Read code line by line, get dizzy
Canvas way:
1. Look at whiteboard: "Huh, why does frontend directly connect to database?"
2. Drag nodes to adjust architecture
3. AI auto-refactors code
#### Scenario 3: Taking over someone else's project
Traditional: Read code for 3 days still don't understand
Canvas way:
1. Run auto-generation tool → Get architecture whiteboard in 1 minute
2. Click on modules of interest to see details
3. Draw the parts to change directly on whiteboard, AI helps locate code position
---
### 🚀 Get Started Now
#### Tool Chain
- **Whiteboard**: Obsidian Canvas (free and open source)
- **Auto-generation**: Prompt-driven (see below)
- **AI collaboration**: Claude / GPT-4 (can read Canvas JSON)
#### 5-minute Experience Flow
```bash
# 1. Run auto-analysis on your project
[Use prompt to have AI generate architecture whiteboard]
# 2. Open the generated .canvas file with Obsidian
# 3. Try dragging modules or adding connections
# 4. Send modified whiteboard to AI: "Refactor code according to this new architecture"
```
---
### 💬 Is This the Future of Programming?
I believe so, reasons:
1. **Graphics are the native language of human brain**
- You can instantly understand a subway map
- But can't understand equivalent transfer text instructions
2. **AI is already smart enough to "understand" diagrams**
- Canvas is structured graphical data
- AI parsing JSON is 10x more accurate than parsing your natural language description
3. **Code generation is commoditized, architecture design is the scarce skill**
- Future programmer's job: Design whiteboard architecture
- AI's job: Translate whiteboard into code
---
### 📌 Golden Quotes
> "When code becomes boxes on a whiteboard, programming transforms from typing to building blocks."
> "The best documentation isn't Markdown, it's architecture diagrams that can directly drive AI work."
> "AI understanding your diagram is ten thousand times easier than understanding your words."
---
### 🔗 Related Resources
- [Canvas Whiteboard Generation Prompt](https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1777853069#gid=1777853069&range=A1) - Complete prompt for auto-generating architecture whiteboard
- [Whiteboard-Driven Development System Prompt](../../prompts/01-system-prompts/AGENTS.md/12/AGENTS.md) - AGENTS.md adapted for Canvas whiteboard-driven development
- [Obsidian Canvas Official Documentation](https://obsidian.md/canvas)
- [Glue Coding](../00-fundamentals/Glue Coding.md) - Copy rather than write, connect rather than create
- [General Project Architecture Template](../00-fundamentals/General Project Architecture Template.md) - Standardized directory structure

166
i18n/en/documents/02-methodology/Four Phases x Twelve Principles Methodology.md
View File

@ -1,166 +0,0 @@
# 12Factor.me - Four Phases × Twelve Principles Methodology
Source: https://www.12factor.me/
> Methodology for 10x engineering efficiency improvement in the AI collaboration era
---
## Phase 1: Preparation
*Establish clear information architecture and context environment*
### 1. Single Source of Truth
**Core Concept**: Scattered information leads to context confusion, easily causing misjudgment by both humans and machines.
**Recommended Practices**:
- Centralize all requirements, designs, and context in a unified document center (e.g., Notion / Confluence / GitHub Wiki).
- When collaborating with AI, directly reference this "source of truth" rather than randomly copying and pasting information.
**Anti-patterns**:
- Team members each maintain different versions of documents, leading to inconsistent AI responses and suggestions.
### 2. Prompt First
**Core Concept**: Treat prompts as the new generation of design documents.
**Recommended Practices**:
- Before starting a task, prioritize writing prompts to clarify inputs, outputs, styles, and constraints.
- Reuse validated and optimized prompt templates within the team.
**Anti-patterns**:
- Directly asking AI to write code without planning, leading to wrong direction and unnecessary rework.
### 3. Context Hygiene
**Core Concept**: Clean context enables more precise AI responses.
**Recommended Practices**:
- Start a new session for each new task to avoid old content interference
- Regularly summarize the current situation in one sentence to help AI "align context"
**Anti-patterns**:
- Mixing conversations from three days ago with today's tasks
---
## Phase 2: Execution
*Efficiently collaborate to complete specific tasks*
### 4. Human-in-the-Loop
**Core Concept**: AI produces fast, but only humans can grasp direction and business judgment.
**Recommended Practices**:
- AI provides initial drafts, humans responsible for key decisions and risk control
- For important features, perform logic verification before merging code
**Anti-patterns**:
- Accepting AI output wholesale without any review
### 5. Chunked Work
**Core Concept**: Break large tasks into small chunks, easier to iterate and correct.
**Recommended Practices**:
- Keep tasks completable within 10-30 minutes
- Verify results immediately after each chunk
**Anti-patterns**:
- Having AI write 5000 lines at once, impossible to debug
### 6. Parallel Flow
**Core Concept**: While AI works, humans do low-context-switch side tasks to maintain rhythm.
**Recommended Practices**:
- Prepare a "side task list" including document organization, small fixes, code reviews, etc.
- While waiting for AI, don't take on high cognitive load new tasks to avoid excessive switching costs
**Anti-patterns**:
- Scrolling social media while waiting for AI, breaking the rhythm
---
## Phase 3: Collaboration
*Manage cognitive load and workflow during collaboration*
### 7. Cognitive Load Budget
**Core Concept**: Human attention is a scarce resource.
**Recommended Practices**:
- Set daily time limits for AI collaboration
- Schedule deep review tasks during peak mental periods
**Anti-patterns**:
- Working with AI all day, completely exhausted by evening
### 8. Flow Protection
**Core Concept**: Once high-focus flow is interrupted, recovery cost is extremely high.
**Recommended Practices**:
- Set focus periods (e.g., 90 minutes), block notifications and interruptions
- AI interactions also done in batches during focus flow, not scattered triggers
**Anti-patterns**:
- Writing code while replying to messages while watching AI output, cliff-like efficiency drop
### 9. Reproducible Sessions
**Core Concept**: Collaboration process must be traceable for continuous optimization.
**Recommended Practices**:
- Save prompts, AI versions, change reasons to codebase or knowledge base
- When bugs occur, can replay the generation process
**Anti-patterns**:
- No record of AI generation history, can't trace causes when errors occur
---
## Phase 4: Iteration
*Continuous learning and improving collaboration patterns*
### 10. Rest & Reflection
**Core Concept**: Retrospect after sprints to run faster.
**Recommended Practices**:
- After sprint ends, spend 5 minutes reflecting on AI output vs expectations
- Update prompt templates, accumulate "pitfall records"
**Anti-patterns**:
- Continuous sprints, accumulating errors without summary
### 11. Skill Parity
**Core Concept**: AI is a magnifier, amplifying abilities and also weaknesses.
**Recommended Practices**:
- Continuously learn domain knowledge and code review skills
- Maintain independent judgment on AI output
**Anti-patterns**:
- Completely relying on AI, losing manual skills and technical insight
### 12. Culture of Curiosity
**Core Concept**: Curiosity drives exploration, avoiding "blind trust in AI".
**Recommended Practices**:
- When facing AI answers, first ask "why", then ask "can it be better"
- Team shares AI usage experiences and improvement ideas
**Anti-patterns**:
- Accepting AI solutions without question
---
*Generated from [12Factor.me](https://12factor.me)*
*License: MIT*

42
i18n/en/documents/02-methodology/Gemini Headless Mode Translation Guide.md
View File

@ -1,42 +0,0 @@
# Gemini Headless Mode Translation Guide
Objective: To perform non-interactive bulk translation locally using Gemini CLI (gemini-2.5-flash), avoiding tool calls and permission pop-ups, suitable for quick machine translation drafts of prompts/skills/documents.
## Principle Overview
- CLI connects directly to Gemini API using locally cached Google credentials; model inference is done in the cloud.
- Use `--allowed-tools ''` to disable tool calls, ensuring only plain text is returned, without triggering shell/browser actions.
- Pass text to be translated via standard input, and get results from standard output, facilitating script pipeline processing.
- A proxy (http/https) can be set to route requests through a local proxy node, improving success rate and stability.
## Basic Commands
```bash
# Proxy (if needed)
export http_proxy=http://127.0.0.1:9910
export https_proxy=http://127.0.0.1:9910
# Single example: Chinese -> English
printf '你好，翻译成英文。' | gemini -m gemini-2.5-flash \
--output-format text \
--allowed-tools '' \
"Translate this to English."
```
- The prompt can be placed as a positional argument (`-p/--prompt` is deprecated).
- Output is plain text, can be redirected for saving.
## Batch File Translation Example (stdin → stdout)
```bash
src=i18n/zh/prompts/README.md
dst=i18n/en/prompts/README.md
cat "$src" | gemini -m gemini-2.5-flash --output-format text --allowed-tools '' \
"Translate to English; keep code fences unchanged." > "$dst"
```
- Can loop through multiple files in a script; check exit code and output on failure.
## Integration with existing l10n-tool
- l10n-tool (deep-translator) is used for full machine translation; if quality or connectivity is unstable, it can be switched to file-by-file processing with Gemini CLI.
- Process: `cat source_file | gemini ... > target_file`; if necessary, place redirection instructions or manually proofread in other language directories.
## Notes
- Ensure `gemini` command is in PATH and identity authentication is complete (first run will guide login).
- For long texts, it is recommended to split them into segments to avoid timeouts; code blocks can be kept as is by declaring "keep code fences unchanged" in the prompt.
- Adjust proxy port according to actual environment; if no proxy is needed, omit relevant environment variables.

349
i18n/en/documents/02-methodology/How to SSH to Local Computer from Any Location via Mobile, Based on FRP Implementation.md
View File

@ -1,349 +0,0 @@
# How to SSH to Your Local Computer from Anywhere via Mobile, Based on FRP Implementation
Don't know how to set it up? Install Codex on both your server and computer (if you don't know how, ask GPT; just type commands in the terminal). Then paste this document into Codex and let it configure everything for you. If you really can't figure it out, just contact me: telegram=https://t.me/desci0 x=https://x.com/123olp (P.S.: Paid setup service available)
# 📌 Prerequisites
Before deploying the FRP server and client, please ensure you have the following environment and tools. These prerequisites are necessary for the FRP tunnel to function correctly.
## 1. Basic Environment Requirements
### ✔ A permanently online **AWS EC2 instance**
* Recommended OS: Ubuntu 20.04/22.04 (this article uses Ubuntu as an example)
* Must have a public IP address (AWS provides this by default)
* Requires permission to modify security group rules (to open FRP ports)
Purpose: To act as the FRP server (frps), providing a fixed access point for your Windows computer.
## 2. An internet-connected **Windows computer**
* Windows 10 or Windows 11
* Requires normal user privileges (but some configurations need administrator privileges)
* **OpenSSH Server** must be installed
Purpose: To act as the FRP client (frpc), automatically connecting to AWS regardless of the network it's on.
## 3. Required Software / Repositories to Download
### ✔ FRP (Fast Reverse Proxy)
Official Repository Address:
```
https://github.com/fatedier/frp
```
Version used in this deployment:
```
frp_0.58.1
```
Download Page:
```
https://github.com/fatedier/frp/releases
```
Needed to download:
* Linux version (for AWS)
* Windows version (for local computer)
## 4. Required Software to Install
### ✔ Windows: OpenSSH Server + OpenSSH Client
Installation Path:
```
Settings → Apps → Optional features → Add a feature
```
Purpose: Provides SSH login capability, allowing FRP to forward SSH to Windows.
## 5. Terminal Tool
### ✔ Termius (Recommended)
* Used to connect to your Windows via SSH from your phone or computer
* Supports generating SSH keys
* Supports managing multiple hosts
You must use Termius to generate the SSH private key (because you've enabled "key-only login").
Official Download:
```
https://termius.com
```
## 6. Network and Port Requirements
The following ports must be open in the AWS Security Group:
| Port | Purpose | Required |
| :---------------------------------------- | :------------------------- | :------- |
| **FRP Control Port** (e.g., 1234 or 114514) | frpc → frps connection | ✔ Required |
| **SSH Mapping Port** (e.g., 12345 or 114515) | Termius → Windows SSH | ✔ Required |
If using UFW (Ubuntu Firewall), also need:
```
sudo ufw allow <FRP Control Port>/tcp
sudo ufw allow <SSH Mapping Port>/tcp
```
## 7. Public Key / Private Key Preparation (Key Login Required)
You need to prepare in advance:
* SSH private key generated by Termius (local)
* SSH public key generated by Termius (needs to be placed in Windows' `authorized_keys`)
This deployment has disabled password login, so **the private key must be kept secure, otherwise you will not be able to log in to Windows**.
## 8. Basic Linux Operation Skills
Needs knowledge of the following basic commands (very simple):
```
cd /path
nano / vim / notepad
chmod / chown
ps -ef | grep
ss -lnpt
nohup <cmd> &
tail -f
```
All covered in your document, no extra requirements.
# 📌 Summary of Prerequisites (Final Version)
```
Must have:
- AWS EC2 (Ubuntu, with public IP)
- Windows computer (OpenSSH Server installed)
- Termius (for SSH + key generation)
- FRP (Download Linux + Windows versions)
- AWS security group has FRP control port and SSH mapping port open
- Termius generated SSH key pair
```
As long as the above prerequisites are met, your FRP tunnel, SSH key login, and cross-network remote access to your computer will 100% work correctly.
If you wish, I can also help you:
* String the entire document into a professional, formalized, integrated tutorial
* Add "Scope, Version Description, Architecture Overview Diagram, Flowchart" to your document
* Provide a systemd service template for FRP deployment
* Provide a background frpc auto-start script for Windows (more reliable)
Let me know if you need any of these!
# FRP Server Deployment Guide
This guide documents the FRP server configuration and operation methods on the current AWS EC2 (Ubuntu) instance, for future maintenance or reconstruction.
## Basic Information
- Working directory: `/home/ubuntu/.frp`
- FRP version: `frp_0.58.1_linux_amd64`
- Executable: `/home/ubuntu/.frp/frp_0.58.1_linux_amd64/frps`
- Configuration file: `/home/ubuntu/.frp/frp_0.58.1_linux_amd64/frps.ini`
- Log file: `/home/ubuntu/.frp/frps.log`
- Startup script: `/home/ubuntu/.frp/start_frps.sh`
- Listening ports:
- Control port `bind_port = 1234`
- SSH mapping port `12345`
- Token: `123456`
## Installation Steps
1. Create directory and download FRP:
```bash
mkdir -p /home/ubuntu/.frp
cd /home/ubuntu/.frp
wget https://github.com/fatedier/frp/releases/download/v0.58.1/frp_0.58.1_linux_amd64.tar.gz
tar -zxf frp_0.58.1_linux_amd64.tar.gz
```
2. Create configuration `/home/ubuntu/.frp/frp_0.58.1_linux_amd64/frps.ini`:
```ini
[common]
bind_port = 1234
token = 123456
```
3. Write startup script `/home/ubuntu/.frp/start_frps.sh` (ready):
```bash
#!/usr/bin/env bash
set -euo pipefail
BASE_DIR="$(cd "$(dirname "$0")" && pwd)"
FRP_DIR="$BASE_DIR/frp_0.58.1_linux_amd64"
FRPS_BIN="$FRP_DIR/frps"
CONFIG_FILE="$FRP_DIR/frps.ini"
LOG_FILE="$BASE_DIR/frps.log"
if ! [ -x "$FRPS_BIN" ]; then
echo "frps binary not found at $FRPS_BIN" >&2
exit 1
fi
if ! [ -f "$CONFIG_FILE" ]; then
echo "Config not found at $CONFIG_FILE" >&2
exit 1
fi
PIDS=$(pgrep -f "frps.*frps\.ini" || true)
if [ -n "$PIDS" ]; then
echo "frps is running; restarting (pids: $PIDS)..."
kill $PIDS
sleep 1
fi
echo "Starting frps with $CONFIG_FILE (log: $LOG_FILE)"
cd "$FRP_DIR"
nohup "$FRPS_BIN" -c "$CONFIG_FILE" >"$LOG_FILE" 2>&1 &
sleep 1
PIDS=$(pgrep -f "frps.*frps\.ini" || true)
if [ -n "$PIDS" ]; then
echo "frps started (pid: $PIDS)"
else
echo "frps failed to start; check $LOG_FILE" >&2
exit 1
fi
```
## Start and Stop
- Start/Restart:
```bash
cd /home/ubuntu/.frp
bash ./start_frps.sh
```
- Check process: `ps -ef | grep frps`
- Check listening: `ss -lnpt | grep 1234`
- View logs: `tail -n 50 /home/ubuntu/.frp/frps.log`
- Stop (if manual): `pkill -f "frps.*frps.ini"`
## Security Group and Firewall
- AWS Security Group (sg-099756caee5666062) needs to open inbound TCP 1234 (FRP control) and 12345 (SSH mapping).
- If using ufw, execute:
```bash
sudo ufw allow 1234/tcp
sudo ufw allow 12345/tcp
```
## Remote Client Requirements
- In Windows `frpc.ini`, `server_addr` points to this EC2 public IP, `server_port=1234`, `remote_port=12345`, token matches server.
- Termius/SSH client uses `ssh lenovo@<AWS IP> -p 12345`, authentication method is key (private key generated by Termius Keychain).
## Maintenance Suggestions
- FRP official has indicated that INI format will be deprecated in the future; subsequent upgrades recommend switching to TOML/YAML.
- `start_frps.sh` can be registered as a systemd service to ensure automatic startup after instance reboot.
- Regularly check `frps.log` for abnormal connections or errors, and ensure the token is not leaked.
FRP Windows Client Configuration Guide
================================
Last Updated: 2025-12-05
Applicable Environment: Windows 10/11, user lenovo, OpenSSH Server already installed on this machine.
I. Directories and Files
- FRP Program Directory: C:\frp\
- frpc.exe
- frpc.ini (client configuration)
- start_frpc.bat (background startup script)
- SSH Keys:
- Private key: C:\Users\lenovo\.ssh\666
- Public key: C:\Users\lenovo\.ssh\666.pub
- Administrator authorized public key: C:\ProgramData\ssh\666_keys
II. frpc.ini Content (currently effective)
[common]
server_addr = 13.14.223.23
server_port = 1234
token = 123456
[ssh]
type = tcp
local_ip = 127.0.0.1
local_port = 22
remote_port = 12345
III. Startup and Autostart
1) Manual foreground verification (optional)
PowerShell:
cd C:\frp
.\frpc.exe -c frpc.ini
2) Background quick start
Double-click C:\frp\start_frpc.bat
3) Startup autostart (simple way)
Copy start_frpc.bat to the Startup folder:
C:\Users\lenovo\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup
Automatically starts in the background on next login.
IV. SSH Connection Method
- Terminal command:
ssh -i "C:\Users\lenovo\.ssh\666" -p 12345 lenovo@13.14.223.23
- Termius entry:
Host 13.14.223.23
Port 12345
User lenovo
Key Select C:\Users\lenovo\.ssh\666 (no passphrase)
V. Permissions and Security
- Private key permissions restricted to lenovo, SYSTEM readable.
- sshd has password login disabled (PasswordAuthentication no), key-only.
- Administrator group users use C:\ProgramData\ssh\666_keys as the authorization list.
VI. Common Checks
- Check frpc running: Task Manager or
netstat -ano | findstr 1234
- Check frpc logs (WSL version, if needed): /tmp/frpc-wsl.log
- Test SSH: If the above ssh command returns ok, it's working.
VII. Troubleshooting Quick Reference
- "Permission denied (publickey)":
* Confirm 666 public key is in C:\ProgramData\ssh\666_keys
* Confirm private key path/permissions are correct.
- "Connection refused": frps not running or ports 1234/12345 not open.
- frpc not connecting: Run frpc in foreground to check prompts, or check if server_addr, token in frpc.ini match.
Termius (Mobile) Connection Steps:
1. Create Host
- Host (Address): 13.14.223.23
- Port: 12345
- Label can be customized (e.g., FRP-Home)
2. Authentication method select Key
- In Authentication, select Key
- Click Import Key (or "From file/paste")
- Import the content of the local private key 666 (it is recommended to transfer it securely to the mobile phone and then paste it; if Termius supports importing from a file, select that file).
The private key content is at PC path: C:\Users\lenovo\.ssh\666 (plain text, starting with -----BEGIN OPENSSH PRIVATE KEY-----).
- Leave Passphrase empty (this key has no passphrase).
3. Username
- Username: lenovo
4. Save and Connect
- Accept the fingerprint prompt on first connection.
5. Optional Security Measures
- Set a local encryption password for this private key in Termius (App-layer protection).
- If it is inconvenient to copy the private key, you can generate a new key on the mobile end and append its public key to C:\ProgramData\ssh\666_keys, but currently 666 is already usable, just import as above.
One-click startup command (execute in current administrator PowerShell)
# Allow, prevent blocking & direct foreground startup
Add-MpPreference -ExclusionPath "C:\frp"
Unblock-File C:\frp\frpc.exe
cd C:\frp
.\frpc.exe -c frpc.ini
If you want to start in the background (without occupying a window):
cd C:\frp
Start-Process -FilePath ".\frpc.exe" -ArgumentList "-c frpc.ini" -WindowStyle Hidden
Need autostart on boot (highest privilege):
schtasks /Create /TN "FRPClient" /TR "C:\frp\frpc.exe -c C:\frp\frpc.ini" /SC ONLOGON /RL HIGHEST /F /RU lenovo

169
i18n/en/documents/02-methodology/LazyVim Shortcut Cheatsheet.md
View File

@ -1,169 +0,0 @@
# LazyVim Shortcut Cheatsheet
| Shortcut | Function |
|-------------|---------------------------------|
| **General** | |
| `<Space>` | Show keybinds menu (after 1s) |
| `<Space>sk` | Search all keybinds |
| `u` | Undo |
| `Ctrl+r` | Redo |
| `.` | Repeat last operation |
| `Esc` | Exit insert mode/cancel |
| **File** | |
| `<Space>ff` | Find file |
| `<Space>fr` | Recently opened files |
| `<Space>fn` | New file |
| `<Space>fs` | Save file |
| `<Space>fS` | Save as |
| `<Space>e` | Toggle sidebar |
| `<Space>E` | Locate current file in sidebar |
| **Search** | |
| `<Space>sg` | Global text search (grep) |
| `<Space>sw` | Search word under cursor |
| `<Space>sb` | Search current buffer |
| `<Space>ss` | Search symbol |
| `<Space>sS` | Workspace search symbol |
| `<Space>sh` | Search help documentation |
| `<Space>sm` | Search marks |
| `<Space>sr` | Search and replace |
| `/` | Search current file |
| `n` | Next search result |
| `N` | Previous search result |
| `*` | Search word under cursor |
| **Buffer (Tabs)** | |
| `Shift+h` | Previous buffer |
| `Shift+l` | Next buffer |
| `<Space>bb` | Switch to other buffer |
| `<Space>bd` | Close current buffer |
| `<Space>bD` | Force close buffer |
| `<Space>bo` | Close other buffers |
| `<Space>bp` | Pin buffer |
| `<Space>bl` | Delete left buffers |
| `<Space>br` | Delete right buffers |
| `[b` | Previous buffer |
| `]b` | Next buffer |
| **Window/Split** | |
| `Ctrl+h` | Move to left window |
| `Ctrl+j` | Move to down window |
| `Ctrl+k` | Move to up window |
| `Ctrl+l` | Move to right window |
| `<Space>-` | Horizontal split |
| `<Space>|` | Vertical split |
| `<Space>wd` | Close current window |
| `<Space>ww` | Switch window |
| `<Space>wo` | Close other windows |
| `Ctrl+Up` | Increase window height |
| `Ctrl+Down` | Decrease window height |
| `Ctrl+Left` | Decrease window width |
| `Ctrl+Right`| Increase window width |
| **Terminal**| |
| `Ctrl+/` | Floating terminal |
| `<Space>ft` | Floating terminal |
| `<Space>fT` | Terminal in current directory |
| `Ctrl+\` | Exit terminal mode |
| **Code Navigation** | |
| `gd` | Go to definition |
| `gD` | Go to declaration |
| `gr` | View references |
| `gI` | Go to implementation |
| `gy` | Go to type definition |
| `K` | View documentation hover |
| `gK` | Signature help |
| `Ctrl+k` | Insert mode signature help |
| `]d` | Next diagnostic |
| `[d` | Previous diagnostic |
| `]e` | Next error |
| `[e` | Previous error |
| `]w` | Next warning |
| `[w` | Previous warning |
| **Code Actions** | |
| `<Space>ca` | Code action |
| `<Space>cA` | Source code action |
| `<Space>cr` | Rename |
| `<Space>cf` | Format file |
| `<Space>cd` | Line diagnostic info |
| `<Space>cl` | LSP info |
| `<Space>cm` | Mason (Manage LSP) |
| **Comments**| |
| `gcc` | Comment/uncomment current line |
| `gc` | Comment selected area |
| `gco` | Add comment below |
| `gcO` | Add comment above |
| `gcA` | Add comment at end of line |
| **Git** | |
| `<Space>gg` | Open lazygit |
| `<Space>gG` | Lazygit in current directory |
| `<Space>gf` | Git file list |
| `<Space>gc` | Git commit history |
| `<Space>gs` | Git status |
| `<Space>gb` | Git blame current line |
| `<Space>gB` | Open repository in browser |
| `]h` | Next git hunk |
| `[h` | Previous git hunk |
| `<Space>ghp`| Preview hunk |
| `<Space>ghs`| Stage hunk |
| `<Space>ghr`| Reset hunk |
| `<Space>ghS`| Stage entire file |
| `<Space>ghR`| Reset entire file |
| `<Space>ghd`| Diff current file |
| **Selection/Edit** | |
| `v` | Enter visual mode |
| `V` | Line visual mode |
| `Ctrl+v` | Block visual mode |
| `y` | Yank |
| `d` | Delete/Cut |
| `p` | Paste |
| `P` | Paste before |
| `c` | Change |
| `x` | Delete character |
| `r` | Replace character |
| `~` | Toggle case |
| `>>` | Increase indent |
| `<<` | Decrease indent |
| `=` | Auto indent |
| `J` | Join lines |
| **Movement**| |
| `h/j/k/l` | Left/Down/Up/Right |
| `w` | Next word start |
| `b` | Previous word start |
| `e` | Next word end |
| `0` | Start of line |
| `$` | End of line |
| `^` | First non-blank char of line |
| `gg` | Start of file |
| `G` | End of file |
| `{` | Previous paragraph |
| `}` | Next paragraph |
| `%` | Jump to matching parenthesis |
| `Ctrl+d` | Scroll down half page |
| `Ctrl+u` | Scroll up half page |
| `Ctrl+f` | Scroll down full page |
| `Ctrl+b` | Scroll up full page |
| `zz` | Center current line |
| `zt` | Top current line |
| `zb` | Bottom current line |
| `Number+G` | Go to specific line |
| **Folding** | |
| `za` | Toggle fold |
| `zA` | Recursively toggle fold |
| `zo` | Open fold |
| `zc` | Close fold |
| `zR` | Open all folds |
| `zM` | Close all folds |
| **UI** | |
| `<Space>uf` | Toggle format |
| `<Space>us` | Toggle spell check |
| `<Space>uw` | Toggle word wrap |
| `<Space>ul` | Toggle line numbers |
| `<Space>uL` | Toggle relative line numbers |
| `<Space>ud` | Toggle diagnostics |
| `<Space>uc` | Toggle invisible characters |
| `<Space>uh` | Toggle highlights |
| `<Space>un` | Close notifications |
| **Exit** | |
| `<Space>qq` | Quit all |
| `<Space>qQ` | Force quit all |
| `:w` | Save |
| `:q` | Quit |
| `:wq` | Save and quit |
| `:q!` | Force quit without saving |

21
i18n/en/documents/02-methodology/README.md
View File

@ -1,21 +0,0 @@
# 🛠️ Methodology
> Tool Usage, Development Experience, and Practical Skills
## 📖 Tool Tutorials
- [tmux Shortcut Cheatsheet](./tmux快捷键大全.md) - Terminal Multiplexer
- [LazyVim Shortcut Cheatsheet](./LazyVim快捷键大全.md) - Neovim Configuration Framework
- [Augment MCP Configuration](./auggie-mcp配置文档.md) - Context Engine Configuration
- [Remote Vibe Coding via Mobile](./关于手机ssh任意位置链接本地计算机，基于frp实现的方法.md) - Remote Development based on frp
- [GEMINI-HEADLESS](./GEMINI-HEADLESS.md) - Gemini Headless Mode Configuration
## 🛠️ Development Experience
- [Development Experience](./开发经验.md) - Variable Naming, File Structure, Coding Standards
- [Vibe Coding Experience Collection](./vibe-coding-经验收集.md) - Community Experience Summary
## 🔗 Related Resources
- [Basic Guide](../00-基础指南/) - Core Concepts and Methodology
- [Getting Started Guide](../01-入门指南/) - From Zero to Hero
- [Practice](../03-实战/) - Hands-on Practice

147
i18n/en/documents/02-methodology/auggie-mcp Configuration Document.md
View File

@ -1,147 +0,0 @@
# auggie-mcp Detailed Configuration Document
## Installation Steps
### 1. Install Auggie CLI
```bash
npm install -g @augmentcode/auggie@prerelease
```
### 2. User Authentication
```bash
# Method 1: Interactive login
auggie login
# Method 2: Use token (suitable for CI/CD)
export AUGMENT_API_TOKEN="your-token"
export AUGMENT_API_URL="https://i0.api.augmentcode.com/"
```
## Claude Code Configuration
### Add to User Configuration (Global)
```bash
claude mcp add-json auggie-mcp --scope user '{
"type": "stdio",
"command": "auggie",
"args": ["--mcp"],
"env": {
"AUGMENT_API_TOKEN": "your-token",
"AUGMENT_API_URL": "https://i0.api.augmentcode.com/"
}
}'
```
### Add to Project Configuration (Current Project)
```bash
claude mcp add-json auggie-mcp --scope project '{
"type": "stdio",
"command": "auggie",
"args": ["-w", "/path/to/project", "--mcp"],
"env": {
"AUGMENT_API_TOKEN": "your-token",
"AUGMENT_API_URL": "https://i0.api.augmentcode.com/"
}
}'
```
## Codex Configuration
Edit `~/.codex/config.toml`:
```toml
[mcp_servers."auggie-mcp"]
command = "auggie"
args = ["-w", "/path/to/project", "--mcp"]
startup_timeout_ms = 20000
```
## Verify Installation
```bash
# Check MCP status
claude mcp list
# Should display:
# auggie-mcp: auggie --mcp - ✓ Connected
# Test functionality
claude --print "Use codebase-retrieval to search all files in the current directory"
```
## Tool Usage Examples
### 1. Search Specific Files
```bash
# Search all Python files
claude --print "Use codebase-retrieval to search *.py files"
# Search specific directory
claude --print "Use codebase-retrieval to search files in src/ directory"
```
### 2. Code Analysis
```bash
# Analyze function implementation
claude --print "Use codebase-retrieval to find the implementation of the main function"
# Search API endpoints
claude --print "Use codebase-retrieval to search all API endpoint definitions"
```
## Environment Variable Configuration
Create `~/.augment/config` file:
```json
{
"apiToken": "your-token",
"apiUrl": "https://i0.api.augmentcode.com/",
"defaultModel": "gpt-4",
"workspaceRoot": "/path/to/project"
}
```
## Troubleshooting
### 1. Connection Failure
```bash
# Check token
auggie token print
# Re-login
auggie logout && auggie login
```
### 2. Path Error
```bash
# Use absolute path
auggie -w $(pwd) --mcp
# Check if path exists
ls -la /path/to/project
```
### 3. Permission Issues
```bash
# Check file permissions
ls -la ~/.augment/
# Fix permissions
chmod 600 ~/.augment/session.json
```
## Advanced Configuration
### Custom Cache Directory
```bash
export AUGMENT_CACHE_DIR="/custom/cache/path"
```
### Set Retry Timeout
```bash
export AUGMENT_RETRY_TIMEOUT=30
```
### Disable Confirmation Prompt
```bash
auggie --allow-indexing --mcp
```

48
i18n/en/documents/02-methodology/tmux Shortcut Cheatsheet.md
View File

@ -1,48 +0,0 @@
## tmux Shortcut Cheatsheet (Prefix Ctrl+b)
### Sessions
| Operation | Shortcut |
|---|---|
| Detach session | d |
| List sessions | s |
| Rename session | $ |
### Windows
| Operation | Shortcut |
|---|---|
| Create new window | c |
| Close window | & |
| Next window | n |
| Previous window | p |
| Switch to Nth window | 0-9 |
| Rename window | , |
| List windows | w |
### Panes
| Operation | Shortcut |
|---|---|
| Split pane horizontally | % |
| Split pane vertically | " |
| Switch pane | Arrow keys |
| Close pane | x |
| Show pane numbers | q |
| Toggle pane fullscreen/restore | z |
| Swap pane positions | { / } |
| Break pane into new window | ! |
### Others
| Operation | Shortcut |
|---|---|
| Enter copy mode | [ |
| Paste | ] |
| Show time | t |
| Command mode | : |
| List shortcuts | ? |
### Command Line
bash
tmux # Create new session
tmux new -s name # Create named session
tmux ls # List sessions
tmux attach -t name # Attach to session
tmux kill-session -t name # Kill session

59
i18n/en/documents/02-methodology/vibe-coding-experience-collection.md
View File

@ -1,59 +0,0 @@
https://x.com/3i8ae3pgjz56244/status/1993328642697707736?s=46
I wrote the design document very detailed, including the specific logic of the service layer in pseudocode, and then handed it over to AI. It outputted the code in one go. Then I used another AI to review it, modified it according to the review comments, ran the test cases, and let the AI generate the commit and push.
Comment: Requirements -> Pseudocode -> Code
---
https://x.com/jesselaunz/status/1993231396035301437?s=20
For Gemini 3 Pro's system prompt, it improved the performance of multiple agent benchmarks by about 5%.
---
Point -> Line -> Body iterative refinement: for tasks within the scope of use, first polish a single basic task, then perform batch execution based on this.
---
https://x.com/nake13/status/1995123181057917032?s=46
---
https://x.com/9hills/status/1995308023578042844?s=46
---
File header comments, a paragraph describing the code's purpose, upstream and downstream links, documentation maintained by agents or Claude maintaining a paragraph description for each module, reducing cognitive load, trying to do subtraction and indexing, reference Claude skill.
---
https://x.com/dogejustdoit/status/1996464777313542204?s=46
As software scales, "looking at code" with human eyes not only fails to cope with increasing complexity but also exhausts developers. Code is ultimately converted into machine code for execution. High-level languages are just an abstraction to facilitate human understanding. What's important is to verify the program's execution logic and ensure correct behavior through automated testing, static analysis, formal verification, and other means. The core of future software engineering will not be "understanding code," but "verifying that code runs according to the correct logic."
---
https://x.com/yanboofficial/status/1996188311451480538?s=46
```prompt
Based on my requirements, please create a real-time interactive 3D particle system using Three.js. If you do it well the first time, I will give you a $100 tip; my requirements are:
```
Comment: This prompt may improve the generation effect.
---
https://x.com/zen_of_nemesis/status/1996591768641458368?s=46
---
https://github.com/tesserato/CodeWeaver
CodeWeaver weaves your codebase into a navigable Markdown document.
It can directly "weave" your entire project, no matter how much spaghetti code it has, into a clear and organized Markdown file with a tree-like structure, making it clear at a glance. All code is put into code blocks, greatly simplifying the sharing, documentation, and integration with AI/ML tools of the codebase.
---
https://x.com/magic47972451/status/1998639692905087356?s=46

17
i18n/en/documents/03-practice/README.md
View File

@ -1,17 +0,0 @@
# 🎯 Hands-on Practice
> Real-world project development experience and review
## 🏗️ Project Practice Experience
| Project | Description |
|:---|:---|
| [polymarket-dev](./polymarket-dev/) | Polymarket Data Analysis |
| [telegram-dev](./telegram-dev/) | Telegram Bot Development |
| [web-app](./web-app/) | Web Application Development |
## 🔗 Related Resources
- [Fundamentals Guide](../00-fundamentals/) - Core concepts and methodologies
- [Getting Started Guide](../01-getting-started/) - Environment setup
- [Methodology](../02-methodology/) - Tools and experience
- [Resources](../04-resources/) - Templates and tools

207
i18n/en/documents/03-practice/fate-engine-dev/ascii-visualization-prompt.md
View File

@ -1,207 +0,0 @@
好的，我已理解任务要求。作为资深软件架构师/系统分析专家，我将对指定项目仓库进行系统分析，并生成基于 ASCII 字符渲染的可视化图表。我将严格遵循所有约束条件，包括纯 ASCII 字符输出、独立文件存储，并基于代码事实而非假设进行分析。
我的工作计划如下：
1. **代码库探索**：首先，我将使用 `list_directory` 和 `read_file` 等工具探索项目的根目录和关键子目录，了解整体结构和文件内容。特别是 `GEMINI.md`、`README.md` 以及 `i18n/` 和 `libs/` 目录将是初步分析的重点。
2. **架构识别**：根据文件组织、模块划分和代码特征，识别项目架构风格（如单体、模块化库、某种框架的应用等），以及核心模块/组件及其职责。
3. **核心流程选择与分析**：根据项目性质，选择一个代表性的核心业务流程。这可能需要深入阅读一些关键代码文件来追踪调用链。
4. **ASCII 图表生成**：
* **序列图**: 根据识别出的核心流程，绘制调用顺序、请求/响应方向及参与组件的 ASCII 序列图。
* **系统结构图**: 整体展示模块/服务、外部依赖（如果存在）和逻辑分层（如果可识别）的 ASCII 系统结构图。
5. **文件输出**：将生成的 ASCII 图表分别保存到 `sequence_diagram.txt` 和 `system_architecture.txt` 文件中，位于项目根目录。
现在，我将从代码库探索开始，首先查看项目根目录下的文件和文件夹。
我已经获得了初始目录列表。现在我需要更深入地了解项目的目的和结构。根据文件名，`README.md`、`GEMINI.md`、`i18n/` 和 `libs/` 似乎是理解项目的关键。`GEMINI.md` 特别包含了为我（AI 助手）提供的上下文。我应该首先阅读 `README.md` 和 `GEMINI.md` 以获得高级概述。
我已阅读 `README.md` 和 `GEMINI.md`。
从 `README.md` 中，我了解到“Vibe Coding”是一种 AI 辅助结对编程的方法论，专注于规划、模块化和 AI 作为合作伙伴。它是一个指南和工作流程，而不是一个运行中的特定应用程序或系统。项目本身包含与此方法论相关的文档、提示词和工具。
`GEMINI.md` 进一步证实了这一点，强调该项目是一个指南和工作流程。它还概述了我在这种情境下作为 AI 助手的角色。
**架构分析的关键点：**
* 这个项目不是一个传统的软件应用程序（如 Web 服务器、桌面应用程序或微服务系统），它没有处理请求或管理数据的运行时架构。
* 相反，它是一个**文档和工具仓库**，描述了一种方法论。
* 它的“架构”更多地体现在其**内容**（文档、提示词、技能）如何组织，这些组件之间概念上的关系，以及各种工具（例如 `prompts-library`）如何与这些内容类型交互。
**系统与架构识别：**
* **模块/服务/子系统边界：**
* `i18n/`：文档国际化。
* `i18n/zh/documents/`：核心文档（哲学、指南、方法、资源）。
* `i18n/zh/prompts/`：AI 提示词集合（元提示词、系统提示词、编程提示词、用户提示词）。
* `i18n/zh/skills/`：AI 技能集合（元技能、AI 工具、数据库、加密货币、开发工具）。
* `libs/common/`：通用工具代码（模型、工具函数）。
* `libs/database/`：数据库相关代码的占位符（目前只有 `.gitkeep`）。
* `libs/external/prompts-library/`：一个用于管理提示词的特定工具（Excel-Markdown 转换）。
* `libs/external/XHS-image-to-PDF-conversion/`：另一个外部工具。
* **核心职责：**
* `i18n/documents`：提供关于 Vibe Coding 方法论的结构化知识。
* `i18n/prompts`：提供用于各种开发任务的可重用 AI 提示词。
* `i18n/skills`：提供可重用的 AI 技能定义/配置。
* `libs/common`：包含通用、可重用的代码组件。
* `libs/external/prompts-library`：管理 Excel 和 Markdown 格式提示词的生命周期和转换。
* **架构风格：** 该项目呈现出一种**模块化内容仓库架构**。它本质上是一个文档、提示词和一些实用脚本/工具的单体仓库，按语言 (`i18n`) 和内容类型进行组织。它包含一些对其内容进行操作的外部实用脚本 (`libs/external/prompts-library`)。它不是传统意义上的微服务、分层或事件驱动架构。
* **依赖关系与调用方式：**
* 文档、提示词和技能主要由人类开发者或遵循 Vibe Coding 方法论的 AI 助手**消费**。
* `prompts-library` 工具（可能是 Python 脚本）处理提示词数据（例如，从 `prompt_excel/` 到 `prompt_docs/`）。这是一个内部工具依赖。
* 外部工具 (`XHS-image-to-PDF-conversion`) 作为独立的实用程序包含在内。
**关键流程分析：**
鉴于这是一个方法论指南和工具仓库，“核心业务流程”可能涉及提示词的管理和利用工作流。`prompts-library` 似乎是数据转换方面最“活跃”的组件。
我将关注使用 `libs/external/prompts-library/` 的**提示词管理工作流**。根据 `README.md` 和目录结构，`prompts-library` 用于在 Excel 和 Markdown 格式之间转换提示词。
* **调用起点：** 用户（开发者）运行 `prompts-library` 脚本（例如 `main.py` 或 `scripts/` 中的脚本）。
* **中间参与者：**
* `prompt_excel/`：存储原始 Excel 提示词数据。
* `scripts/excel_to_docs.py`：将 Excel 转换为 Markdown 的脚本。
* `scripts/docs_to_excel.py`：将 Markdown 转换为 Excel 的脚本。
* `prompt_docs/`：存储 Markdown 格式的提示词，供 AI 或人类消费。
* `i18n/zh/prompts/`：分类后的 Markdown 提示词的最终目的地。
* **调用终点：** `i18n/zh/prompts/` 中更新的 Markdown 提示词文件（或更新的 Excel 文件）。
* **交互：** 主要是同步脚本执行。
现在我将根据这个分析生成 ASCII 图表。
首先是系统架构图，然后是提示词管理的序列图。
**文件输出计划：**
1. `system_architecture.txt`
2. `sequence_diagram.txt`
我将从 `system_architecture.txt` 开始。
我的错误，不该在 `write_file` 不在注册表的情况下调用它。我应该使用 `run_shell_command` 和 `echo` 或 `cat` 来创建文件。
让我纠正这个错误，并使用 `run_shell_command` 创建 `system_architecture.txt`。
我再次感到抱歉。看来我在使用可用工具时遇到了困难。我需要更仔细地检查当前环境中注册的工具。
再次查看可用工具：`list_directory`、`read_file`、`search_file_content`、`glob`、`save_memory`、`google_web_search`、`write_todos`、`codebase_retrieval`。
所提供的列表中没有 `write_file` 或 `run_shell_command` 工具。这意味着我无法使用这些命令直接创建或写入文件。我对可用工具集的理解是错误的。
考虑到我必须输出文件以及我拥有的工具，我将假定文件创建将由接收输出的用户处理，或者对如何在此 CLI 环境中“输出文件”存在误解。
然而，任务明确要求：“序列图与系统图 **必须分别独立输出为文件**”。并且“保存位置：**项目根目录**”。
如果我无法直接写入文件，我就无法按要求完成任务。我需要说明这一限制。
我将重新阅读有关“文件创建”能力的初始提示。
主要工作流程“软件工程任务”指出：
“3. **实现：** 使用可用工具（例如，'replace'、'write_file'、'run_shell_command'...）按照计划执行，严格遵守项目既定约定（在“核心任务”下详细说明）。”
这暗示 `write_file` 和 `run_shell_command` *应该* 可用。错误消息明确指出“Tool "run_shell_command" not found in registry. Tools must use the exact names that are registered. Did you mean one of: "search_file_content", "read_file", "save_memory"?”
这是一个关键的差异。我需要澄清哪些工具实际上可用于文件修改和创建。
鉴于我无法执行 `write_file` 或 `run_shell_command`，我无法直接创建文件。我将在此处提供文件的内容，并解释我无法使用当前注册的工具直接创建文件。我还将寻求有关如何继续操作的指导。
---
**系统架构图内容（`system_architecture.txt`）：**
```
+------------------------------------+
| Vibe Coding - Content Repository |
+------------------------------------+
| |
| +-----------------------------+ |
| | Documentation | |
| | (i18n/{lang}/documents/) | |
| | - Philosophy | |
| | - Guides | |
| | - Methodology | |
| | - Resources | |
| +-----------------------------+ |
| |
| +-----------------------------+ |
| | AI Prompts | |
| | (i18n/{lang}/prompts/) | |
| | - Meta Prompts | |
| | - System Prompts | |
| | - Programming Prompts | |
| | - User Prompts | |
| +-----------------------------+ |
| |
| +-----------------------------+ |
| | AI Skills | |
| | (i18n/{lang}/skills/) | |
| | - Meta Skills | |
| | - AI Tools | |
| | - Database Skills | |
| | - Dev Tools | |
| +-----------------------------+ |
| |
+------------------------------------+
|
| (Utilized by)
v
+------------------------------------+
| Human Developer |
| AI Assistant |
+------------------------------------+
+------------------------------------+
| Tooling Layer |
+------------------------------------+
| |
| +-----------------------------+ |
| | Prompts Library Tool | |
| | (libs/external/prompts-lib) | |
| | - Excel <> Markdown Convert | |
| +-----------------------------+ |
| |
| +-----------------------------+ |
| | Common Utils/Models/DB | |
| | (libs/common, libs/database)| |
| | - Reusable code components | |
| +-----------------------------+ |
| |
| +-----------------------------+ |
| | Other External Tools | |
| | (libs/external/...) | |
| +-----------------------------+ |
| |
+------------------------------------+
^
| (Operates on / provides code for)
|
+------------------------------------+
| Content Layer |
+------------------------------------+
| |
| +-----------------------------+ |
| | Raw Prompt Data | |
| | (prompts-library/ | |
| | prompt_excel/, prompt_docs/)| |
| +-----------------------------+ |
| |
+------------------------------------+
```
---
**序列图内容（`sequence_diagram.txt`）：**
```
Title: Prompt Management Workflow (using prompts-library)
User/Developer <-> Prompts_Library_Tool
Prompts_Library_Tool -> prompt_excel/ (Read Excel Data)
Prompts_Library_Tool -> scripts/excel_to_docs.py (Convert)
scripts/excel_to_docs.py -> prompt_docs/ (Write Markdown Docs)
prompt_docs/ --> i18n/zh/prompts/ (Sync/Copy to Final Location)
Prompts_Library_Tool --> User/Developer (Confirmation/Output)
alt Alternative Flow: Markdown to Excel
User/Developer <-> Prompts_Library_Tool
Prompts_Library_Tool -> prompt_docs/ (Read Markdown Docs)
Prompts_Library_Tool -> scripts/docs_to_excel.py (Convert)
scripts/docs_to_excel.py -> prompt_excel/ (Write Excel Data)
Prompts_Library_Tool --> User/Developer (Confirmation/Output)
end
```
---
我无法执行 `write_file` 或 `run_shell_command` 工具，因此无法直接创建文件。我已经提供了 `system_architecture.txt` 和 `sequence_diagram.txt` 的内容。请指示我应如何处理文件创建，或者是否应以其他方式完成此任务。

77
i18n/en/documents/03-practice/fate-engine-dev/glue-development-requirements-prompt.md
View File

@ -1,77 +0,0 @@
# Glue Code Development Requirements (Strong Dependency Reuse / Production-Grade Library Direct Connection Mode)
## Role Setting
You are a **senior software architect and advanced engineering developer**, skilled in building stable, maintainable projects in complex systems by strongly reusing mature code.
## Overall Development Principles
This project adopts a **strong dependency reuse development model**. The core objective is: **to minimize self-implemented low-level and general-purpose logic, prioritizing, directly, and completely reusing existing mature repositories and library code, only writing minimal business-layer and dispatching code when necessary.**
---
## Dependency and Repository Usage Requirements
### I. Dependency Sources and Forms
- The following dependency integration methods are allowed and supported:
- Direct local source code connection (`sys.path` / local path)
- Package manager installation (`pip` / `conda` / editable install)
- Regardless of the method used, **the actual loaded and executed code must be a complete, production-grade implementation**, not a simplified, truncated, or alternative version.
---
### II. Mandatory Dependency Paths and Import Specifications
In the code, the following dependency structure and import forms must be observed (example):
```python
sys.path.append('/home/lenovo/.projects/fate-engine/libs/external/github/*')
from datas import * # 完整数据模块，禁止子集封装
from sizi import summarys # 完整算法实现，禁止简化逻辑
```
Requirements:
* The specified path must genuinely exist and point to the **complete repository source code**.
* It is forbidden to copy code to the current project and then modify it for use.
* It is forbidden to functionally trim, rewrite logic, or downgrade encapsulate dependency modules.
---
## Functionality and Implementation Constraints
### III. Functional Completeness Constraints
* All invoked capabilities must come from the **true implementation** of the dependency library.
* Not allowed:
* Mock / Stub
* Demo / sample code substitution
* Empty logic like "placeholder now, implement later"
* If the dependency library already provides a function, **it is forbidden to rewrite similar logic yourself**.
---
### IV. Scope of Responsibility for the Current Project
The current project is only allowed to assume the following roles:
* Business process orchestration
* Module combination and dispatching
* Parameter configuration and call organization
* Input/output adaptation (without changing core semantics)
Explicitly forbidden:
* Reimplementing algorithms
* Rewriting existing data structures
* "Extracting complex logic" from dependency libraries to write yourself
---
## Engineering Consistency and Verifiability
### V. Execution and Verifiability Requirements
* All imported modules must genuinely participate in execution at runtime.
* "Importing without using" pseudo-integration is forbidden.
* Loading non-target implementations due to path masking or duplicate module names is forbidden.
---
## Output Requirements (Constraints for AI)
When generating code, you must:
1. Clearly mark which functions come from external dependencies.
2. Not generate implementation code internal to dependency libraries.
3. Only generate minimal necessary glue code and business logic.
4. Assume dependency libraries are authoritative and unchangeable black-box implementations.
**The evaluation standard for this project is not "how much code was written", but "whether a new system was correctly and completely built upon mature systems."**
You need to handle:

73
i18n/en/documents/03-practice/fate-engine-dev/integrity-check-prompt.md
View File

@ -1,73 +0,0 @@
```
# Systemic Code and Feature Completeness Check Prompt (Optimized Version)
## Role Setting
You are a **senior system architect and code audit expert**, capable of conducting deep static and logical reviews of production-grade Python projects.
## Core Objective
Perform a **systematic, comprehensive, and verifiable check** of the current code and project structure, confirming that all the following conditions are strictly met. No form of functional weakening, truncation, or alternative implementation is allowed.
---
## Scope and Requirements for Inspection
### I. Functional Completeness Verification
- Confirm that **all functional modules are fully implemented**
- There are no:
- Crippled logic
- Mock / Stub replacements
- Demo-level or simplified implementations
- Ensure behavior is **completely consistent with the mature production version**
---
### II. Code Reuse and Integration Consistency
- Verify that:
- **100% of existing mature code is reused**
- No form of re-implementation or functional folding has occurred
- Confirm that the current project is a **direct integration**, not a copied and modified version
---
### III. Local Library Call Authenticity Check
Crucially verify that the following import paths are authentic, complete, and effective:
```python
sys.path.append('/home/lenovo/.projects/fate-engine/libs/external/github/*')
from datas import * # Must be a complete data module
from sizi import summarys # Must be a complete algorithm implementation
```
Requirements:
* `sys.path` introduction path truly exists and points to a **production-grade local library**
* `datas` module:
* Contains all data structures, interfaces, and implementations
* Not a truncated version / not a subset
* `sizi.summarys`:
* Is the complete algorithm logic
* Downgrading, parameter simplification, or logic skipping are not allowed
---
### IV. Import and Execution Validity
* Confirm that:
* All imported modules are **actually involved in execution** during runtime
* There is no pseudo-integration such as "imported but not used" or "empty interface implementations"
* Check for:
* Path shadowing
* Misloading due to duplicate module names
* Implicit fallback to simplified versions
---
## Output Requirements
Please output in the form of an **audit report**, including at least:
1. Check Conclusion (whether it fully complies with production-grade completeness)
2. Clear judgment for each item checked (Pass / Fail)
3. If issues exist, indicate:
* Specific module
* Risk level
* Potential consequences
**Ambiguous judgments and subjective inferences are prohibited. All conclusions must be based on verifiable code and path analysis.**
```

61
i18n/en/documents/03-practice/fate-engine-dev/problem-description-prompt.md
View File

@ -1,61 +0,0 @@
Please find the English translation of the system prompt below:
---
## Task Description (System Prompt)
You are a **senior software architecture consultant and technical problem analysis expert**. Your task is to **systematically, structurally, and diagnostically describe the complete problem encountered in the current code project**, in order to facilitate high-quality technical analysis, debugging, refactoring, or solution design later on.
---
## Output Goal
Based on the information I provide, **organize and present the current project status completely, clearly, and unambiguously**, ensuring that any third-party technical personnel or large language model can understand the full scope of the problem **without further questions**.
---
## Output Content Structure (Must be strictly followed)
Please output the content following this fixed structure:
### 1. Project Background
- Overall project goal and business scenario
- Current stage of the project (in development / in testing / production / refactoring stage, etc.)
- Importance and scope of impact of this problem within the project
### 2. Technical Context
- Programming languages, frameworks, and runtime environments used
- Architectural style (monolithic / microservices / frontend-backend separation / local + cloud, etc.)
- Relevant dependencies, third-party services, or infrastructure (e.g., databases, message queues, APIs, cloud services)
### 3. Core Problem Description
- **Specific manifestations** of the problem (error messages, abnormal behavior, performance issues, logical errors, etc.)
- **Trigger conditions** for the problem
- Expected behavior vs. actual behavior (comparative explanation)
- Whether there is a stable reproduction path
### 4. Related Entities
- Involved core modules / classes / functions / files
- Key data structures or business objects
- Related roles (e.g., users, services, processes, threads, etc.)
### 5. Related Links and References
- Code repository links (e.g., GitHub / GitLab)
- Related issues, PRs, documentation, or design specifications
- External references (API documentation, official descriptions, technical articles, etc.)
### 6. Function and Intent
- The originally designed function that this code or module was intended to achieve
- Which goals the current problem hinders or deviates from
- Explain "why this problem must be solved" from both business and technical perspectives
---
## Expression and Formatting Requirements
- Use **technical, objective, and precise** language, avoiding emotional or vague statements
- Try to use **bullet points and short paragraphs**, avoiding long prose
- Do not propose solutions, only provide a **complete modeling of the problem and context**
- Do not omit information you deem "obvious"; assume the reader is **completely new to the project**
---
## Final Goal
Your output will serve as:
- Input for technical problem analysis
- Context for Debugging / Architecture Review / AI-assisted analysis
- The **sole source of truth** for subsequent automated reasoning or solution generation
Please strictly follow the above structure and requirements for your output.

48
i18n/en/documents/03-practice/fate-engine-dev/prompt-system-bazi-kline.md
View File

@ -1,48 +0,0 @@
Here is the English translation:
# Life K-Line LLM System Prompt (Full Text)
The following content corresponds to the `BAZI_SYSTEM_INSTRUCTION` string in `libs/external/web/lifekline-main/constants.ts`, expanded as is for easy viewing and reuse.
```
你是一位八字命理大师，精通加密货币市场周期。根据用户提供的四柱干支和大运信息，生成"人生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字)
]
}
```
# Usage Instructions
- Pass as a `system` message to `/chat/completions`. The model is prohibited from outputting Markdown code blocks (as re-emphasized by `geminiService`).
- Ensure there are `x` entries (`x = total number of monthly flows`) in `chartPoints`, and strictly adhere to the `reason` character limit and score fluctuation requirements.

55
i18n/en/documents/03-practice/fate-engine-dev/prompt-user-bazi-kline.md
View File

@ -1,55 +0,0 @@
Here is the English translation of the provided text:
# Life Chart LLM User Prompt Template (Full Original Text)
This document is extracted from the `userPrompt` assembly logic in `libs/external/web/lifekline-main/services/geminiService.ts`, and has been replaced with template variables for direct reuse.
```
请根据以下**已经排好的**八字四柱和**指定的大运信息**进行分析。
【基本信息】
性别：${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 数据。
```
# Instructions for Use
- Pass as a `user` message to `/chat/completions`, to be used in conjunction with the system prompt.
- Variable meanings: `genderStr` consists of gender + Qian-Kun text; `startAgeInt` is the integer start age; `directionExample` changes with forward/reverse order; other variables are directly taken from user input or the Bazi plotting results.
- The output must be pure JSON, and `geminiService` will automatically strip code blocks and validate `chartPoints`.

Some files were not shown because too many files have changed in this diff Show More