ai-coding-wiki

ai-coding-wiki 是一个面向中文、没有编程经验的新手用户的 AI Coding 学习 Skill。

它适合这样的场景：用户正在用 Claude Code 或 Codex CLI 做产品，遇到看不懂的代码、终端命令、技术术语、报错、技术栈选择或工程流程，希望一边实践一边学习，并把每次学习沉淀到一个可检索、可复习、可生长的 Obsidian 知识库。

核心特点

• 中文解释优先，适合编程小白。
• 专业术语保留英文原词，并补充英文全称、中文翻译、来源、一句话理解。
• 每个概念都会落到 AI Coding 知识地图中（Mermaid / 文本线框 / Canvas 三种模式之一），不是孤立解释。
• 笔记按"用途"分三类：概念解释（concept）、代码精读（code-reading）、调试记录（debug-session）。
• Wiki 页面是 Karpathy 风格的"摘要式知识库"：不堆问答流水，只放概念条目 + 手动 curate 出的核心要点 / 常见误解 / 表达模板。
• 使用脚本维护配置、初始化、写入、检索、curate、迁移和校验，减少 Obsidian 知识库写乱的风险。
• 避免污染 Obsidian Graph View：不生成 README.md wiki 节点，模板不用 .md 后缀，日志不用 Markdown 文件。

Skill 结构

ai-coding-wiki/
├── SKILL.md
├── README.md
├── references/
│   └── templates.md
└── scripts/
    ├── common.py
    ├── kb_config.py
    ├── kb_init.py
    ├── kb_ingest.py
    ├── kb_curate.py
    ├── kb_migrate.py
    ├── kb_search.py
    └── kb_validate.py

首次使用

先设置默认 Obsidian vault 路径。建议新建一个独立 vault，不要混进已有主知识库。

python3 scripts/kb_config.py set-path "$HOME/Documents/AI-Coding-Wiki" --create
python3 scripts/kb_init.py

默认路径会保存到：

~/.config/ai-coding-wiki/config.yaml

生成的 Vault 结构

真实 vault 不应该随 Skill 一起开源。下面只是结构示意。

AI-Coding-Wiki/
├── raw/
│   ├── concepts/
│   │   └── 什么是 Swift.md
│   ├── code-readings/
│   ├── debug/
│   ├── maps/
│   │   └── *.canvas       # 由 /json-canvas skill 生成的知识地图
│   └── assets/
├── wiki/
│   ├── 01-terminal-and-environment（终端与环境）.md
│   ├── 02-ai-coding-tools（AI Coding 工具链）.md
│   ├── 03-clear-product-requirements（清晰产品需求）.md
│   ├── 04-tech-stack-selection（技术栈选择）.md
│   ├── 05-project-architecture（项目架构）.md
│   ├── 06-frontend-implementation（前端实现）.md
│   ├── 07-backend-api-database（后端、API 与数据库）.md
│   ├── 08-ai-features-llm（AI 功能与 LLM）.md
│   ├── 09-testing-debugging（测试与调试）.md
│   ├── 10-deployment-operations（部署与运维）.md
│   └── 11-real-product-cases（真实产品案例）.md
└── _system/
    ├── AI Coding 索引.md
    ├── AI Coding 知识地图.md
    ├── activity.log
    ├── config.yaml
    ├── 未归类问题.md
    └── templates/
        ├── concept-note.template
        ├── concept-entry.template
        └── wiki-entry.template

三种笔记类型

kind	用途	写入路径	是否回写 wiki
concept	解释一个术语 / 概念	raw/concepts/	是（追加到对应 area wiki 的 ## 概念条目）
code-reading	精读一段代码	raw/code-readings/	否
debug-session	排查一次报错	raw/debug/	否

概念解释协议

写 kind: concept 笔记时，必须给出五个身份字段 + 一张知识地图。

身份五字段（写入 frontmatter）：

• term：英文原词（如 Swift）
• full_name：英文全称
• zh：中文翻译
• source：来源（谁发布、什么时候、什么背景）
• one_liner：一句话理解

知识地图三选一（写入 ## 知识地图位置 section）：

1. ```mermaid 块 — Obsidian 直接渲染。
2. ```text 块 — ASCII / 文本线框图。
3. ![[xxx.canvas]] 嵌入 — 复杂关系图，先用 /json-canvas skill 在 raw/maps/ 生成。

kb_validate 会强制检查这两件事。

常用脚本

# 查看配置
python3 scripts/kb_config.py show

# 设置默认 vault
python3 scripts/kb_config.py set-path "$HOME/Documents/AI-Coding-Wiki" --create

# 初始化 vault
python3 scripts/kb_init.py

# 迁移旧结构到 v1.2 schema
python3 scripts/kb_migrate.py

# 搜索历史知识（可选 --kind 限定）
python3 scripts/kb_search.py "SDK 是什么意思"
python3 scripts/kb_search.py "report" --kind code-reading

# 保存一次概念解释
python3 scripts/kb_ingest.py \
  --kind concept \
  --title "什么是 Swift" \
  --term Swift \
  --full-name Swift \
  --zh "Swift" \
  --source "Apple 在 2014 年 WWDC 发布的开源编程语言" \
  --one-liner "Apple 推出的现代编程语言，用于 iOS / macOS / 等 Apple 平台 App 开发" \
  --area 04-tech-stack-selection \
  --map-file /tmp/swift-map.md \
  --question "什么是 Swift？" \
  --answer-file /tmp/swift-answer.md

# 保存一次代码精读 / 调试记录（不回写 wiki）
python3 scripts/kb_ingest.py --kind code-reading --title ... --question ... --answer-file ...
python3 scripts/kb_ingest.py --kind debug-session --title ... --question ... --answer-file ...

# 由 LLM 提炼某个 area 的核心要点 / 常见误解 / 表达模板
python3 scripts/kb_curate.py --area 04-tech-stack-selection                    # 打印 prompt 与原料
python3 scripts/kb_curate.py --area 04-tech-stack-selection --apply curate.md  # 写回 wiki

# 校验 vault
python3 scripts/kb_validate.py

写入策略

默认是 ask_before_write，也就是回答后先询问是否保存。

python3 scripts/kb_config.py set-policy auto_write
python3 scripts/kb_config.py set-policy ask_before_write

图谱命名原则

Obsidian Graph View 是复习知识关系的重要窗口，所以节点必须有真实指导意义。

• Wiki 页面使用带编号的语义文件名，例如 01-terminal-and-environment（终端与环境）.md。
• 不使用 README.md 作为 wiki 页面。
• 模板使用 .template 后缀，不进入图谱。
• 日志使用 activity.log，不进入图谱。
• 内部链接指向真实文件名，需要展示完整标题时使用 [[文件名|展示标题]]；文件名等于展示标题时简化为 [[文件名]]。

如果你 fork 这个仓库

• 这个仓库只管理 Skill 源码，不要把真实 Obsidian vault 一起提交。
• vault 应单独 git 化，与 Skill 源码物理分离。
• 如需演示，单独建 examples/sample-vault/，只放虚构或脱敏样例。

License

MIT License — see LICENSE.