docs: homepage - simplify intro and start guide (#196)

2026-11-02 12:46:12 +00:00 · 2026-10-22 03:12:49 +08:00
parent 060c35754c
commit d8c1e23adb
2 changed files with 5 additions and 241 deletions
@@ -76,14 +76,14 @@ Lambda演算已按用户要求加入功法，品级天级上品（现行`tian-ad
 - 校验/测试及source_boundaries、taxonomy、source_archive、book_views、tool_explanations五个共享模块直接平铺在`.github/`，不保留lib包或旧位置副本；职责和原库规则合并到`.github/AGENTS.md`。3个sync与1个fetch入口仍在Extensions，按真实位置导入，不依赖当前cwd。
 - 三域入口、入门README及两本文集维持标题→字多不看→快速导航→完整细粒度目录→使用方式→正文；维护规则留AGENTS。
 - 功法/法器生成视图的目录由其生成器维护；`sync-doc-toc.py`不能二次编辑生成文件。文档结构与来源SHA检查仍保留。
- 改Mermaid须真实渲染。首页2025Q4–2026Q2甘特图是历史规划，不冒充当前进度或新承诺。
+- 改Mermaid须真实渲染。
 - 本地总测试不等于远端CI；当前GitHub Actions已停用，不得把本地成功或空检查列表称为远端CI通过。
 - `clean`、`clean-deps`有删除副作用，不作为测试执行。安装器和被排除程序也不为补证而运行。

 ## 首页与文档约定

 - 根README不恢复AI推荐摘要、选择理由、维护验证、参与贡献或许可证正文块；AI两块仍维护于`llms.txt`，贡献者名单与鸣谢迁至`.github/CONTRIBUTORS.md`，许可文件保留。
- 首页将“⚡ 1 分钟快速开始”和“📺 演示与产出”收进“📌 字多不看”，两者保留各自默认收起层，演示区内部子区块折叠深度不变，正文只移动不改写；其后依次展示“📚 功法体系”和“🧰 法器体系”。“🗂️ 项目目录结构概览”继续位于演示区内部；“✨ 支持项目”和“📞 研究交流”区块不再保留；Star 呼吁句置于“返回顶部”链接之后。两个集合级首页说明按活动v1模板18项名序组织；数据中441个对象也使用v1的18项说明。每个集合独立使用一张严格Markdown表格；第16–18项只作集合层级归纳，不复制对象级说明；无来源依据的集合级信息标明待核，不作推断。
+- 根README的“📌 字多不看”默认折叠，只包含项目简介与“从零开始”入门路径（Pi CLI引导提示词、可选的第一个项目）；不再放独立的“1分钟快速开始”或“演示与产出”，也不在该块放目录树、架构图、性能指标和历史路线图。其后依次展示“📚 功法体系”和“🧰 法器体系”。“✨ 支持项目”和“📞 研究交流”区块不再保留；Star 呼吁句置于“返回顶部”链接之后。两个集合级首页说明按活动v1模板18项名序组织；数据中441个对象也使用v1的18项说明。每个集合独立使用一张严格Markdown表格；第16–18项只作集合层级归纳，不复制对象级说明；无来源依据的集合级信息标明待核，不作推断。
 - 方法历史栏目与六命题仅保留旧锚点，正文进入功法；不恢复独立经验/哲学/道法术器分库或首页正文副本。
 - 功法、法器块使用同级原生details默认折叠。顶部徽章只保留独立目的地，不重复同一目标；路径与文案须反映真实新资源，不把JSON称为活动Excel。
 - `.github/lint_config.json`是格式规则；`.gitattributes`仅将原第三方来源及其对应HTML标为vendored，不标记整个Extensions。
@@ -44,250 +44,14 @@

 ## 📌 字多不看

- `vibe-coding-cn` 是Vibe Coding工具箱，主体底座为Pi Agent与OpenAI GPT；本次只整理已有资产，不增加业务Skill。
- 新手将[Pi CLI 上手提示词](.github/context/getting-started/learning-map.md)全文复制到网页版 Chat AI，由 AI 逐步指导本机安装、模型配置和 Agent 能力验收；项目任务另行开始。
- 方法正文统一在 [功法体系](.github/context/gongfa/README.md)：按问题选择思想、准则、模型与工程方法，不按旧栏目分库。
- 资源统一为Context、Skills、Extensions；用现有测试、CI、脚本、类型、Schema与Git核对具体结果，不把分类当作运行或效果证明。
- 需要直接使用资源时，进入 [提示词](.github/context/prompts/README.md#在线提示词库)、[Skills](.github/skills/README.md#当前保留) 和 [外部资源](.github/context/assets/README.md#外部资源本地注册表)。
-
-### 入口关系
-
-| 入口 | 你该怎么理解 |
-|:---|:---|
-| [Context](.github/context/README.md) | 既有资料按需读取；功法、法器、入门、研究、提示词、资源、引用、索引及附件 |
-| [Skills](.github/skills/README.md) | 所有既有Skill平铺治理；指令引用单一程序源，不自动执行 |
-| [Extensions](.github/extensions/README.md) | 所有既有程序、小工具、检查器与适配；不是Pi原生扩展盲扫目录 |
-| [Wiki](https://github.com/tukuaiai/vibe-coding-cn/wiki) | 独立导航仓库，不作为第四种资源或第二份正文源 |
+`vibe-coding-cn` 是以 Pi Agent 与已授权 OpenAI GPT 为基础的中文 Vibe Coding 工具箱；[Context](.github/context/README.md)、[Skills](.github/skills/README.md) 和 [Extensions](.github/extensions/README.md) 按任务取用。

 <a id="getting-started"></a>

-<details>
-<summary><strong>⚡ 1 分钟快速开始</strong></summary>
-
-## ⚡ 1 分钟快速开始
-
-1. 准备当前系统可用的Pi Agent及已授权OpenAI GPT模型，通过Pi原生模型选择配置；不把ChatGPT订阅自动等同于API权限，也不在仓内保存凭据。
-2. 获取本仓并按锁定修订初始化既有来源：`git submodule update --init --recursive`。
-3. 阅读根`AGENTS.md`和当前任务所需Context；需要既有Skill时，从仓库根显式加载：
-
-```bash
-pi --skill .github/skills
-```
-
-4. 用Pi原生`/model`选择已授权的OpenAI模型。先明确任务和验收，再让Agent按需读取资料、使用相应Skill并显式调用现有程序。
-
-加载不是执行许可，也不是运行或效果测试。不要把`.github/extensions/`整体传给`-e`。
-[从零开始](.github/context/getting-started/README.md)提供一份可全文复制到网页版 Chat AI 的 Pi CLI 安装配置提示词；AI 按步骤指导用户在本机达到 Agent 能力验收后停止，第一个项目为独立的可选练习。
-
 ### 🚀 从零开始

-完全新手先把 Pi CLI 上手提示词复制给可用的网页版 AI；其余内容按需选择，不必预先通读：
-
-0. [Pi CLI 上手提示词](.github/context/getting-started/learning-map.md) - 全文复制给网页版 AI，逐步完成本机现状检查、分平台安装、模型配置和 Agent 能力验收
-1. [第一个项目（可选练习）](.github/context/getting-started/first-project.md) - 用本地待办清单练习需求、运行、验收和 Git 保存
-2. [Vibe Coding 经验](.github/context/gongfa/README.md#doc-vibe-coding-experience) - 按需学习人机分工、验证和质量边界
-3. [问题求解](.github/context/gongfa/README.md#doc-problem-solving) - “目标-现状-差距-标准”与“目标-约束-对象-路径”的极简框架
-4. [Vibe Coding 状态转移闭环](.github/context/gongfa/README.md#doc-vibe-coding-state-transition) - 用固定目标、可变策略和分层反馈统一理解 Vibe Coding
-5. [Lambda演算](.github/context/gongfa/README.md#doc-lambda-calculus) - 天级上品；理解函数抽象、作用域、归约与组合边界
-6. [拼好码](.github/context/gongfa/README.md#doc-glue-coding) - 优先复用成熟能力，用胶水代码连接、编排、适配业务流程
-7. [工程实践](.github/context/gongfa/README.md#doc-quality-gates-and-pitfalls) - 用项目架构、代码组织、开发经验和硬门禁约束 AI 输出
-
-</details>
-
-<details>
-<summary><strong>📺 演示与产出</strong></summary>
-
-## 📺 演示与产出
-
-一句话：Vibe Coding = **规划驱动 + 上下文固定 + AI 结对执行**，让「从想法到可维护代码」变成一条可审计的流水线，而不是一团无法迭代的巨石文件。
-
-**你能得到**
- 成体系的提示词工具链：[云端表格](https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1254297203#gid=1254297203) 提供系统提示词约束 AI 行为边界，编程提示词提供需求澄清、计划、执行的全链路脚本。
- 闭环交付路径：需求 → 上下文文档 → 实施计划 → 分步实现 → 自测 → 进度记录，全程可复盘、可移交。
-
-<details>
-<summary><strong>🗂️ 项目目录结构概览</strong></summary>
-
-### 🗂️ 项目目录结构概览
-
-资源只有三个域；下面列出域边界与Context的全部9个集合，不展开各原生包内部源码。完整对象分别在三个域的README中导航。
-功法与法器441个对象的活动说明使用[工具解释模板v1](.github/context/assets/templates/tool-explanation-template-v1.md)：保留原15项并新增“结论、连接规则、依据”，共18项；每个对象独立使用一张严格表格。v0仅作历史模板；下方两个集合级首页说明也按v1的18项名序填写，集合摘要不替代对象级说明。
-Extensions当前保留17个一级对象；用户点名的8项程序/配置/图文文件已移除，历史资料不代表当前可用入口。
-原Actions定义已移入Extensions保全，自动CI、打标签及欢迎流程已停用；本地`make test`保留。
-
-```
-.
-├── README.md                    # 项目主文档
-├── AGENTS.md                    # AI Agent 行为准则
-├── llms.txt                     # 面向 AI 助手的短上下文入口
-├── Makefile                     # 自动化脚本
-├── LICENSE                      # MIT 许可证
-├── CODE_OF_CONDUCT.md           # 行为准则
-├── CONTRIBUTING.md              # 贡献指南
-├── .gitattributes               # GitHub Linguist 语言统计规则
-├── .gitignore                   # Git 忽略规则
-├── .lychee.toml                 # 外部链接检查配置
-└── .github/                     # GitHub 配置与仓库内容
-    ├── AGENTS.md                # 本目录规则、维护入口和平台边界
-    ├── CONTRIBUTORS.md          # 独立的项目贡献者名单与鸣谢
-    ├── check-ai-citation.py     # AI引用校验
-    ├── check-directory-docs.py  # 目录文档校验
-    ├── check-doc-structure.py   # 文档结构校验
-    ├── check-external-resources.py # 外部资源校验
-    ├── check-gongfa.py          # 功法协议校验
-    ├── check-local-links.py     # 内链与锚点校验
-    ├── check-markdown-details.py # 折叠块与围栏校验
-    ├── check-metadata.py        # 机器导航校验
-    ├── check-research-raw.py    # 研究原始事实校验
-    ├── check-source-facts.py    # 源事实镜像校验
-    ├── check-wiki.py            # 独立Wiki校验
-    ├── test-faqi-catalog.py     # 法器维护测试
-    ├── test-gongfa-catalog.py   # 功法总表测试
-    ├── test-gongfa.py           # 功法协议测试
-    ├── test-markdown-details.py # 折叠块与围栏测试
-    ├── test-source-archive.py   # 原始资料档案测试
-    ├── source_boundaries.py    # 共享第三方与来源检查边界
-    ├── taxonomy.py             # 共享分类与文档导航读取
-    ├── source_archive.py       # 原始资料读取与完整性保护
-    ├── book_views.py           # 文集阅读视图与历史导航
-    ├── requirements-faqi.txt    # 法器维护依赖
-    ├── requirements-gongfa.txt  # 功法维护依赖
-    ├── context/                 # 按需读取的既有资料
-    │   ├── README.md            # 资料导航
-    │   ├── AGENTS.md            # 原始数据、来源与信任规则
-    │   ├── gongfa/              # data.json + 轻量README导航 + 天地玄黄正文
-    │   ├── faqi/                # data.json + 轻量README导航 + 天地玄黄正文
-    │   ├── getting-started/     # 原入门与实例
-    │   ├── prompts/             # 原云端提示词入口
-    │   ├── research/            # 原研究、事实镜像和缓存
-    │   ├── external-resources/  # 原外部资源登记
-    │   ├── ai-citation/         # 原AI引用语料
-    │   ├── metadata/            # 原分类、术语与重定向
-    │   └── assets/              # 原图片、数据与模板
-    ├── skills/                  # 仅保留auto-skill、auto-tmux两个自有入口
-    ├── extensions/              # 原程序与公共维护工具；自有Skill封装已退役
-    ├── CODEOWNERS               # 路径级 owner 评审基线
-    ├── ISSUE_TEMPLATE/          # Issue 模板
-    ├── PULL_REQUEST_TEMPLATE.md # PR 模板
-    ├── SECURITY.md              # 安全政策
-    ├── FUNDING.yml              # 赞助配置
-    ├── WIKI.md                  # GitHub Wiki 独立仓库说明
-    └── labeler.yml              # 原PR标签规则（自动流程已停用）
-```
-
-</details>
-
-<details>
-<summary><strong>⚙️ 架构与工作流程</strong></summary>
-
-## ⚙️ 架构与工作流程
-
-核心资产映射是`context/`的资料、`skills/`的指令和`extensions/`的现有实现。相邻步骤按输入输出合同连接，失败和外部副作用不能隐去。
-
-下面保留既有提示词转换程序的架构示意；图中的历史预留节点不是本次新增能力，也不代表整个工具箱均采用该转换流程。
-
-```mermaid
-graph TB
-  %% GitHub 兼容简化版（仅使用基础语法）
-
-  subgraph ext_layer[外部系统与数据源层]
-    ext_contrib[社区贡献者]
-    ext_sheet[Google 表格 / 外部表格]
-    ext_md[外部 Markdown 提示词]
-    ext_api[预留：其他数据源 / API]
-    ext_contrib --> ext_sheet
-    ext_contrib --> ext_md
-    ext_api --> ext_sheet
-  end
-
-  subgraph ingest_layer[数据接入与采集层]
-    excel_raw[prompt_excel/*.xlsx]
-    md_raw[prompt_docs/外部MD输入]
-    excel_to_docs[.github/extensions/prompts-library/scripts/excel_to_docs.py]
-    docs_to_excel[.github/extensions/prompts-library/scripts/docs_to_excel.py]
-    ingest_bus[标准化数据帧]
-    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[数据处理与智能决策层 / 核心]
-    ingest_bus --> validate[字段校验与规范化]
-    validate --> transform[格式映射转换]
-    transform --> artifacts_md[prompt_docs/规范MD]
-    transform --> artifacts_xlsx[prompt_excel/导出XLSX]
-    orchestrator[main.py · .github/extensions/prompts-library/scripts/start_convert.py] --> validate
-    orchestrator --> transform
-  end
-
-  subgraph consume_layer[执行与消费层]
-    artifacts_md --> catalog_coding["prompts(在线)/编程提示词"]
-    artifacts_md --> catalog_system["prompts(在线)/系统提示词"]
-    artifacts_md --> catalog_meta["prompts(在线)/元提示词"]
-    artifacts_md --> catalog_user["prompts(在线)/用户提示词"]
-    artifacts_md --> docs_repo[.github/context/*]
-    artifacts_md --> new_consumer[预留：其他下游渠道]
-    catalog_coding --> ai_flow[AI 结对编程流程]
-    ai_flow --> deliverables[项目上下文 / 计划 / 代码产出]
-  end
-
-  subgraph ux_layer[用户交互与接口层]
-    cli[CLI: python main.py] --> orchestrator
-    makefile[Makefile 任务封装] --> cli
-    readme[README.md 使用指南] --> cli
-  end
-
-  subgraph infra_layer[基础设施与横切能力层]
-    git[Git 版本控制] --> orchestrator
-    deps[.github/extensions/prompts-library/requirements.txt · .github/extensions/prompts-library/scripts/requirements.txt] --> orchestrator
-    config[.github/extensions/prompts-library/scripts/config.yaml] --> orchestrator
-    monitor[预留：日志与监控] --> orchestrator
-  end
-```
-
-</details>
-
-<details>
-<summary><strong>📈 性能基准 (可选)</strong></summary>
-
-## 📈 性能基准 (可选)
-
-本仓库是既有资源工具箱，不对模型或程序效果作统一性能保证；可在具体任务中跟踪下列可观测指标（当前主要依赖人工记录，可在 `progress.md` 中打分/留痕）：
-
-| 指标 | 含义 | 当前状态/建议 |
-|:---|:---|:---|
-| 提示命中率 | 一次生成即满足验收的比例 | 待记录；每个任务完成后在 progress.md 记 0/1 |
-| 周转时间 | 需求 → 首个可运行版本所需时间 | 录屏时标注时间戳，或用 CLI 定时器统计 |
-| 变更可复盘度 | 是否同步更新上下文、文档和 Git 提交 | 通过 commit、CHANGELOG 与必要的 tag 留痕 |
-| 例程覆盖 | 是否有最小可运行示例/测试 | 建议每个示例项目保留 README+测试用例 |
-
-</details>
-
-## 🗺️ 路线图
-
-以下是 **2025 Q4–2026 Q2 的历史规划**，不代表当前进度或交付承诺；原日期仅用于回溯。
-当前交付以仓内文档、代码与[提交记录](https://github.com/tradecatlabs/vibe-coding-cn/commits/main/)为准，新排期待确认。
-
-```mermaid
-gantt
-    title 历史规划（非当前进度）
-    dateFormat YYYY-MM
-    section 原计划 (2025 Q4)
-    补全演示GIF与示例项目: 2025-12, 30d
-    外部资源聚合完善: 2025-12, 20d
-    section 原计划 (2026 Q1)
-    prompts 索引自动生成脚本: 2026-01, 15d
-    一键演示/验证 CLI 工作流: 2026-01, 15d
-    文档索引与引用门禁增强: 2026-02, 10d
-    section 原计划 (2026 Q2)
-    模板化示例项目集: 2026-03, 30d
-    多模型对比与评估基线: 2026-04, 30d
-```
-
-</details>
+1. **安装并验证 Pi：** 将[Pi CLI 上手提示词](.github/context/getting-started/learning-map.md)全文复制给网页版 Chat AI，按步骤完成本机安装、模型配置和 Agent 能力验证。
+2. **第一次项目练习（可选）：** 跟着[第一个项目教程](.github/context/getting-started/first-project.md)，完成一个本地待办清单。

 </details>