docs: add research domains and resource registry

- add local external resources registry - add research domain contract and per-repository research domains - add raw fact snapshot governance and validation scripts Validation: - make test - git diff --check HEAD~1..HEAD Note: - welcome workflow failed because its action input names are stale; core content CI passed.
2026-08-19 13:58:05 +00:00 · 2026-07-03 08:20:22 +08:00
parent 2253a46935
commit a8099f52fe
254 changed files with 28589 additions and 165 deletions
@@ -0,0 +1,12 @@
+# raw/ Agent 指南
+
+本目录是 `luzhenqian/ai-coding-lab` 的原始事实层。
+
+## 维护规则
+
+- 只保存从研究对象拉取的一手材料，不写分析判断。
+- `repository/` 是本地 Git 工作树，刷新时由脚本 clone 或 fast-forward pull。
+- 不手工改写 `*.raw.*` 文件内容；需要刷新时运行 `python3 scripts/fetch-research-raw.py`。
+- `sources.yml` 必须记录拉取时间、来源命令和每个文件的状态。
+- 外部 README 原文必须保存为 `.txt`，避免本仓库 Markdown 链接检查误判。
+- 分析、判断、采用建议和沉淀路径写回上一级 `README.md`、`analysis.md` 或 `decisions.md`。
@@ -0,0 +1,16 @@
+# raw 事实层
+
+本目录保存 `luzhenqian/ai-coding-lab` 的本地原始材料快照。
+
+这里不写分析结论，只保存可复查的一手资料：
+
+- `sources.yml`：来源清单、拉取时间、命令和文件状态。
+- `repository/`：Git 仓库工作树；本目录由 `.gitignore` 忽略，只作为本地研究材料。
+- `github-repo.raw.json`：GitHub 仓库元数据。
+- `github-readme.raw.md.txt`：GitHub README 原文快照。
+- `github-license.raw.txt`：GitHub license 原文快照；仓库无 license 时可能不存在。
+- `github-root-contents.raw.json`：默认分支根目录内容快照。
+- `github-languages.raw.json`：GitHub language 统计快照。
+- `github-latest-release.raw.json`：最新 release 快照；无 release 时可能不存在。
+
+`repository/` 是外部源码快照，不参与本仓库 Markdown、链接、README/AGENTS 覆盖检查。原始 README 使用 `.txt` 后缀保存，避免其中的外部相对链接被本仓库 Markdown 链接检查误判。
@@ -0,0 +1,8 @@
+{
+  "TypeScript": 1167193,
+  "Shell": 213974,
+  "CSS": 61997,
+  "Python": 4597,
+  "JavaScript": 3718,
+  "HTML": 3436
+}
@@ -0,0 +1,94 @@
+# AI Coding Lab
+
+从零开始，用 AI 学编程、做 AI 应用。每个项目都是一次完整的实战。
+
+> [English Version](./README.en.md)
+
+## 这是什么
+
+AI Coding Lab 是一个 AI 实战教程合集，涵盖 **AI 编程** 和 **AI 应用开发** 两大方向。每个项目从「零基础」到「可上线」，全程用 AI 辅助完成。不教语法，不讲理论——只做项目，在实战中学会跟 AI 协作。
+
+## 项目列表
+
+### AI 编程
+
+用 AI 辅助编写代码，学习软件开发。
+
+#### Vibe Coding（氛围编程）
+
+用自然语言描述需求，让 AI 直接生成代码。适合零基础入门。
+
+| # | 项目 | 难度 | 你将做出什么 |
+|---|------|------|-------------|
+| 1 | [个人链接页](./vibe-coding/bio-link-page/) | ⭐ 入门 | 一个类似 Linktree 的个人主页，10 分钟完成 |
+| 2 | [个人博客](./vibe-coding/nextjs-blog/) | ⭐⭐ 初级 | 一个全栈博客系统，支持文章管理、分类标签、评论 |
+| 3 | [个人博客（评论系统）](./vibe-coding/nextjs-blog-comment/) | ⭐⭐ 初级 | 在博客基础上增加嵌套评论回复功能 |
+| 4 | [FlowBoard 看板](./vibe-coding/flow-board/) | ⭐⭐⭐ 进阶 | 个人 Kanban 看板，支持拖拽排序、多看板、标签、Checklist、搜索过滤、归档、快捷键 |
+
+#### Skills（技能定制）
+
+给 AI 写 SOP，让它按你的标准做事。写一次规范，无限复用。
+
+| # | 项目 | 难度 | 你将做出什么 |
+|---|------|------|-------------|
+| 1 | [Claude Skills 实战](./skills/) | ⭐⭐ 初级 | 3 个实用 Skill（博客生成器、Commit 规范、发票生成器）+ API 调用 Demo |
+
+### AI 应用
+
+动手构建 RAG、Chatbot、Agent 等 AI 应用，掌握主流 AI 开发模式。
+
+#### RAG
+
+检索增强生成（RAG）实战项目。
+
+| # | 项目 | 难度 | 你将做出什么 |
+|---|------|------|-------------|
+| 1 | [员工手册问答机器人](./rag/ask-book/) | ⭐⭐⭐ 进阶 | 一个 RAG 聊天机器人，上传 PDF 即可问答 |
+
+#### Chatbot
+
+AI 聊天机器人实战项目。
+
+| # | 项目 | 难度 | 你将做出什么 |
+|---|------|------|-------------|
+| 1 | [Mnemo 记忆聊天助手](./chatbot/mnemo/) | ⭐⭐⭐⭐ 高级 | 一个带长期记忆的 AI 聊天助手，支持文档上传、语义检索、双轨记忆提取 |
+
+#### Agent
+
+AI Agent 实战项目。
+
+| # | 项目 | 难度 | 你将做出什么 |
+|---|------|------|-------------|
+| 1 | [仓库分析器](./agent/repo-analyzer/) | ⭐⭐⭐ 进阶 | 一个分析代码仓库的 AI Agent |
+| 2 | [JobSpy 求职分析助手](./agent/job-spy/) | ⭐⭐⭐ 进阶 | AI 解析 JD + 匹配简历，链式分析 vs 单次分析对比，输出求职策略 |
+| 3 | [ResearchHub 多源调研助手](./agent/research-hub/) | ⭐⭐⭐ 进阶 | AI 四路并行调研，输入公司名即出分析报告（并行化模式实战） |
+| 4 | [Agent 编排模式实战](./agent/mastra-orchestration/) | ⭐⭐⭐⭐ 高级 | 用 Mastra 实现 4 种 Agent 编排模式（Supervisor / Workflow / Handoff / Council）+ 混合编排，配套 React Flow 可视化 |
+
+## 适合谁
+
+- **完全零基础**：不懂代码也能跟着做，从 Vibe Coding 开始
+- **有一定基础**：想学习如何用 AI 提升开发效率
+- **对 AI 编程好奇**：想知道「AI 写代码」到底靠不靠谱
+- **想做 AI 应用**：想动手构建 RAG、Chatbot、Agent 等 AI 产品
+
+## 如何使用
+
+1. 选一个感兴趣的项目
+2. 打开项目文件夹里的 README
+3. 跟着步骤做
+
+每个项目都是独立的，不需要按顺序来。
+
+## 推荐工具
+
+| 工具 | 说明 | 适合场景 |
+|------|------|---------|
+| [Claude Code](https://claude.ai/claude-code) | AI 命令行编程助手 | 全场景适用，高效协作 |
+
+## 许可证
+
+MIT
+
+---
+
+*如果觉得有帮助，欢迎 Star 和分享！有问题请在 [Issues](https://github.com/luzhenqian/ai-coding-lab/issues) 中提出。*
@@ -0,0 +1,26 @@
+{
+  "createdAt": "2026-03-06T07:56:42Z",
+  "defaultBranchRef": {
+    "name": "main"
+  },
+  "description": "适合所有人的 AI 编程、AI 应用开发的实战教程——从 Vibe Coding 到 Agent、RAG，循序渐进，边学边做。",
+  "forkCount": 20,
+  "homepageUrl": "",
+  "isArchived": false,
+  "isFork": false,
+  "isMirror": false,
+  "latestRelease": null,
+  "licenseInfo": null,
+  "nameWithOwner": "luzhenqian/ai-coding-lab",
+  "primaryLanguage": {
+    "name": "TypeScript"
+  },
+  "pushedAt": "2026-05-18T13:56:01Z",
+  "repositoryTopics": null,
+  "stargazerCount": 144,
+  "updatedAt": "2026-07-02T12:41:02Z",
+  "url": "https://github.com/luzhenqian/ai-coding-lab",
+  "watchers": {
+    "totalCount": 0
+  }
+}
@@ -0,0 +1,162 @@
+[
+  {
+    "name": ".claude",
+    "path": ".claude",
+    "sha": "c32db14935832b24c40c29eb17c8ea9845a1911f",
+    "size": 0,
+    "url": "https://api.github.com/repos/luzhenqian/ai-coding-lab/contents/.claude?ref=main",
+    "html_url": "https://github.com/luzhenqian/ai-coding-lab/tree/main/.claude",
+    "git_url": "https://api.github.com/repos/luzhenqian/ai-coding-lab/git/trees/c32db14935832b24c40c29eb17c8ea9845a1911f",
+    "download_url": null,
+    "type": "dir",
+    "_links": {
+      "self": "https://api.github.com/repos/luzhenqian/ai-coding-lab/contents/.claude?ref=main",
+      "git": "https://api.github.com/repos/luzhenqian/ai-coding-lab/git/trees/c32db14935832b24c40c29eb17c8ea9845a1911f",
+      "html": "https://github.com/luzhenqian/ai-coding-lab/tree/main/.claude"
+    }
+  },
+  {
+    "name": ".gitignore",
+    "path": ".gitignore",
+    "sha": "bb5210c115be41db14bae67cc5859d4ba0516beb",
+    "size": 272,
+    "url": "https://api.github.com/repos/luzhenqian/ai-coding-lab/contents/.gitignore?ref=main",
+    "html_url": "https://github.com/luzhenqian/ai-coding-lab/blob/main/.gitignore",
+    "git_url": "https://api.github.com/repos/luzhenqian/ai-coding-lab/git/blobs/bb5210c115be41db14bae67cc5859d4ba0516beb",
+    "download_url": "https://raw.githubusercontent.com/luzhenqian/ai-coding-lab/main/.gitignore",
+    "type": "file",
+    "_links": {
+      "self": "https://api.github.com/repos/luzhenqian/ai-coding-lab/contents/.gitignore?ref=main",
+      "git": "https://api.github.com/repos/luzhenqian/ai-coding-lab/git/blobs/bb5210c115be41db14bae67cc5859d4ba0516beb",
+      "html": "https://github.com/luzhenqian/ai-coding-lab/blob/main/.gitignore"
+    }
+  },
+  {
+    "name": "README.en.md",
+    "path": "README.en.md",
+    "sha": "ffbf742ba6aa9e8c9727a601dec1a77d7f3ae47e",
+    "size": 4257,
+    "url": "https://api.github.com/repos/luzhenqian/ai-coding-lab/contents/README.en.md?ref=main",
+    "html_url": "https://github.com/luzhenqian/ai-coding-lab/blob/main/README.en.md",
+    "git_url": "https://api.github.com/repos/luzhenqian/ai-coding-lab/git/blobs/ffbf742ba6aa9e8c9727a601dec1a77d7f3ae47e",
+    "download_url": "https://raw.githubusercontent.com/luzhenqian/ai-coding-lab/main/README.en.md",
+    "type": "file",
+    "_links": {
+      "self": "https://api.github.com/repos/luzhenqian/ai-coding-lab/contents/README.en.md?ref=main",
+      "git": "https://api.github.com/repos/luzhenqian/ai-coding-lab/git/blobs/ffbf742ba6aa9e8c9727a601dec1a77d7f3ae47e",
+      "html": "https://github.com/luzhenqian/ai-coding-lab/blob/main/README.en.md"
+    }
+  },
+  {
+    "name": "README.md",
+    "path": "README.md",
+    "sha": "fe96eae5aafad7a00fdeda749c2899218c5cdff8",
+    "size": 3927,
+    "url": "https://api.github.com/repos/luzhenqian/ai-coding-lab/contents/README.md?ref=main",
+    "html_url": "https://github.com/luzhenqian/ai-coding-lab/blob/main/README.md",
+    "git_url": "https://api.github.com/repos/luzhenqian/ai-coding-lab/git/blobs/fe96eae5aafad7a00fdeda749c2899218c5cdff8",
+    "download_url": "https://raw.githubusercontent.com/luzhenqian/ai-coding-lab/main/README.md",
+    "type": "file",
+    "_links": {
+      "self": "https://api.github.com/repos/luzhenqian/ai-coding-lab/contents/README.md?ref=main",
+      "git": "https://api.github.com/repos/luzhenqian/ai-coding-lab/git/blobs/fe96eae5aafad7a00fdeda749c2899218c5cdff8",
+      "html": "https://github.com/luzhenqian/ai-coding-lab/blob/main/README.md"
+    }
+  },
+  {
+    "name": "agent",
+    "path": "agent",
+    "sha": "ba5adfb408714bc936d676dfcfdb3279c11d61c5",
+    "size": 0,
+    "url": "https://api.github.com/repos/luzhenqian/ai-coding-lab/contents/agent?ref=main",
+    "html_url": "https://github.com/luzhenqian/ai-coding-lab/tree/main/agent",
+    "git_url": "https://api.github.com/repos/luzhenqian/ai-coding-lab/git/trees/ba5adfb408714bc936d676dfcfdb3279c11d61c5",
+    "download_url": null,
+    "type": "dir",
+    "_links": {
+      "self": "https://api.github.com/repos/luzhenqian/ai-coding-lab/contents/agent?ref=main",
+      "git": "https://api.github.com/repos/luzhenqian/ai-coding-lab/git/trees/ba5adfb408714bc936d676dfcfdb3279c11d61c5",
+      "html": "https://github.com/luzhenqian/ai-coding-lab/tree/main/agent"
+    }
+  },
+  {
+    "name": "chatbot",
+    "path": "chatbot",
+    "sha": "29550ebff8a56c0e74f401536a3667251b9f031a",
+    "size": 0,
+    "url": "https://api.github.com/repos/luzhenqian/ai-coding-lab/contents/chatbot?ref=main",
+    "html_url": "https://github.com/luzhenqian/ai-coding-lab/tree/main/chatbot",
+    "git_url": "https://api.github.com/repos/luzhenqian/ai-coding-lab/git/trees/29550ebff8a56c0e74f401536a3667251b9f031a",
+    "download_url": null,
+    "type": "dir",
+    "_links": {
+      "self": "https://api.github.com/repos/luzhenqian/ai-coding-lab/contents/chatbot?ref=main",
+      "git": "https://api.github.com/repos/luzhenqian/ai-coding-lab/git/trees/29550ebff8a56c0e74f401536a3667251b9f031a",
+      "html": "https://github.com/luzhenqian/ai-coding-lab/tree/main/chatbot"
+    }
+  },
+  {
+    "name": "creative",
+    "path": "creative",
+    "sha": "b3998a3203d675aa8bd04efc7bb98107e9d5bda6",
+    "size": 0,
+    "url": "https://api.github.com/repos/luzhenqian/ai-coding-lab/contents/creative?ref=main",
+    "html_url": "https://github.com/luzhenqian/ai-coding-lab/tree/main/creative",
+    "git_url": "https://api.github.com/repos/luzhenqian/ai-coding-lab/git/trees/b3998a3203d675aa8bd04efc7bb98107e9d5bda6",
+    "download_url": null,
+    "type": "dir",
+    "_links": {
+      "self": "https://api.github.com/repos/luzhenqian/ai-coding-lab/contents/creative?ref=main",
+      "git": "https://api.github.com/repos/luzhenqian/ai-coding-lab/git/trees/b3998a3203d675aa8bd04efc7bb98107e9d5bda6",
+      "html": "https://github.com/luzhenqian/ai-coding-lab/tree/main/creative"
+    }
+  },
+  {
+    "name": "rag",
+    "path": "rag",
+    "sha": "79b7993c1521dc397e87a1234cd70e73c49763da",
+    "size": 0,
+    "url": "https://api.github.com/repos/luzhenqian/ai-coding-lab/contents/rag?ref=main",
+    "html_url": "https://github.com/luzhenqian/ai-coding-lab/tree/main/rag",
+    "git_url": "https://api.github.com/repos/luzhenqian/ai-coding-lab/git/trees/79b7993c1521dc397e87a1234cd70e73c49763da",
+    "download_url": null,
+    "type": "dir",
+    "_links": {
+      "self": "https://api.github.com/repos/luzhenqian/ai-coding-lab/contents/rag?ref=main",
+      "git": "https://api.github.com/repos/luzhenqian/ai-coding-lab/git/trees/79b7993c1521dc397e87a1234cd70e73c49763da",
+      "html": "https://github.com/luzhenqian/ai-coding-lab/tree/main/rag"
+    }
+  },
+  {
+    "name": "skills",
+    "path": "skills",
+    "sha": "377d48ecd35f66f01d100e9ad64e2e8db6b65bac",
+    "size": 0,
+    "url": "https://api.github.com/repos/luzhenqian/ai-coding-lab/contents/skills?ref=main",
+    "html_url": "https://github.com/luzhenqian/ai-coding-lab/tree/main/skills",
+    "git_url": "https://api.github.com/repos/luzhenqian/ai-coding-lab/git/trees/377d48ecd35f66f01d100e9ad64e2e8db6b65bac",
+    "download_url": null,
+    "type": "dir",
+    "_links": {
+      "self": "https://api.github.com/repos/luzhenqian/ai-coding-lab/contents/skills?ref=main",
+      "git": "https://api.github.com/repos/luzhenqian/ai-coding-lab/git/trees/377d48ecd35f66f01d100e9ad64e2e8db6b65bac",
+      "html": "https://github.com/luzhenqian/ai-coding-lab/tree/main/skills"
+    }
+  },
+  {
+    "name": "vibe-coding",
+    "path": "vibe-coding",
+    "sha": "1bcf4ea1f6f6a57cfcf0ae1fcb97331c5ee37033",
+    "size": 0,
+    "url": "https://api.github.com/repos/luzhenqian/ai-coding-lab/contents/vibe-coding?ref=main",
+    "html_url": "https://github.com/luzhenqian/ai-coding-lab/tree/main/vibe-coding",
+    "git_url": "https://api.github.com/repos/luzhenqian/ai-coding-lab/git/trees/1bcf4ea1f6f6a57cfcf0ae1fcb97331c5ee37033",
+    "download_url": null,
+    "type": "dir",
+    "_links": {
+      "self": "https://api.github.com/repos/luzhenqian/ai-coding-lab/contents/vibe-coding?ref=main",
+      "git": "https://api.github.com/repos/luzhenqian/ai-coding-lab/git/trees/1bcf4ea1f6f6a57cfcf0ae1fcb97331c5ee37033",
+      "html": "https://github.com/luzhenqian/ai-coding-lab/tree/main/vibe-coding"
+    }
+  }
+]
@@ -0,0 +1,39 @@
+version: 1
+domain_id: luzhenqian-ai-coding-lab
+object:
+  type: github_repository
+  name: luzhenqian/ai-coding-lab
+  url: https://github.com/luzhenqian/ai-coding-lab
+pulled_at: '2026-07-02T22:47:14+00:00'
+puller: scripts/fetch-research-raw.py
+files:
+  - path: repository/
+    kind: git-working-tree
+    status: ok
+    source: 'git clone --depth=1 --single-branch --no-tags https://github.com/luzhenqian/ai-coding-lab.git docs/research/luzhenqian-ai-coding-lab/raw/repository'
+  - path: github-repo.raw.json
+    kind: repository-metadata
+    status: ok
+    source: 'gh repo view luzhenqian/ai-coding-lab --json nameWithOwner,url,description,homepageUrl,isArchived,isFork,isMirror,defaultBranchRef,licenseInfo,primaryLanguage,repositoryTopics,stargazerCount,forkCount,watchers,createdAt,updatedAt,pushedAt,latestRelease --jq .'
+  - path: github-readme.raw.md.txt
+    kind: readme
+    status: ok
+    source: 'gh api repos/luzhenqian/ai-coding-lab/readme -H Accept: application/vnd.github.raw'
+  - path: github-license.raw.txt
+    kind: license
+    status: missing_or_error
+    source: 'gh api repos/luzhenqian/ai-coding-lab/license -H Accept: application/vnd.github.raw'
+    message: 'gh: Not Found (HTTP 404)'
+  - path: github-root-contents.raw.json
+    kind: root-contents
+    status: ok
+    source: 'gh api repos/luzhenqian/ai-coding-lab/contents'
+  - path: github-languages.raw.json
+    kind: languages
+    status: ok
+    source: 'gh api repos/luzhenqian/ai-coding-lab/languages'
+  - path: github-latest-release.raw.json
+    kind: latest-release
+    status: missing_or_error
+    source: 'gh api repos/luzhenqian/ai-coding-lab/releases/latest'
+    message: 'gh: Not Found (HTTP 404)'