Skip to content

Commit 1dc3615

Browse files
hjnnjhhjnnjh
committed
docs(meta): enhance hierarchical AGENTS.md and reorganize posts
- Update root AGENTS.md with detailed project structure and conventions - Add commit/branch metadata (ef16499, main) - Expand stack details (VitePress 1.5.0, 16 Claude Skills) - Document image path migration strategy (img/ → images/YYYY/) - Add SHARED RESOURCES section - Enhance anti-patterns list (7 explicit prohibitions) - Create hierarchical AGENTS.md knowledge base via /init-deep - New: docs/.vitepress/AGENTS.md (VitePress config guide, 54 lines) - New: docs/posts/agent-basics/AGENTS.md (category-specific rules, 47 lines) - Update: docs/AGENTS.md (content source guide, 46 lines) - Add CLAUDE.md for AI agent instructions (Chinese language preference) - Reorganize posts from flat to category-based structure - Move: docs/posts/2026/*.md → docs/posts/{category}/YYYY-MM-DD-slug.md - agent-basics: 5 articles (LLM basics, memory, context, collaboration, evaluation) - coding-agent: 1 article (Agent Skills intro) - Delete: docs/posts/2026/ (old flat structure) - Update site navigation and metadata - docs/index.md: Update hero tagline spacing - docs/about/index.md: Fix author name formatting - docs/categories/*.md: Update article links to new paths - docs/SKILLS-GUIDE.md: Minor formatting corrections Files: +372 lines, -270 lines across 17 files Knowledge base: 5 AGENTS.md files (root + 4 subdirs) Article structure: Flat (2026/) → Category-based (agent-basics/, coding-agent/)
1 parent ef16499 commit 1dc3615

17 files changed

Lines changed: 1707 additions & 209 deletions

‎AGENTS.md‎

Lines changed: 48 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,75 @@
11
# PROJECT KNOWLEDGE BASE
22

3-
**Generated:** 2026-02-13
4-
**Stack:** VitePress 1.5+ (Vue 3, TS), GitHub Pages, Claude Skills
3+
**Generated:** 2026-02-14
4+
**Commit:** ef16499
5+
**Branch:** main
6+
**Stack:** VitePress 1.5.0 (Vue 3, TS), GitHub Pages, 16 Claude Skills
57

68
## OVERVIEW
7-
Static technical blog sharing Coding Agent applications in academic research. Single-module VitePress architecture with no backend.
9+
Static technical blog sharing Coding Agent applications in academic research. Single-module VitePress architecture with no backend. Core asset: 16 AI Skills in `.claude/skills/` for content production workflow.
810

911
## STRUCTURE
1012
```
1113
.
1214
├── docs/ # Content source & VitePress config
13-
│ ├── .vitepress/ # Site config, theme, & build logic
14-
│ ├── posts/ # Blog articles (YYYY/MM/DD-slug.md)
15-
│ ├── categories/ # Category index pages
16-
│ └── public/ # Static assets (images)
17-
├── .claude/skills/ # 12+ Custom AI agent skills
15+
│ ├── .vitepress/ # Site config (config.mts), theme (custom.css, index.ts)
16+
│ ├── posts/ # Blog articles (STRICT: {category}/YYYY-MM-DD-slug.md)
17+
│ ├── categories/ # 5 category index pages (ascending order)
18+
│ └── public/ # Static assets (img/ for legacy, images/YYYY/ for new)
19+
├── .claude/skills/ # 16 AI Skills (mermaid-tools, fact-checker, etc.)
1820
└── .github/workflows/ # CI/CD (deploy.yml)
1921
```
2022

2123
## WHERE TO LOOK
2224
| Task | Location | Notes |
2325
|------|----------|-------|
24-
| **Site Config** | `docs/.vitepress/config.mts` | Nav, Sidebar, SEO, Mermaid |
25-
| **Theme/Styles** | `docs/.vitepress/theme/` | Custom CSS (`custom.css`), Layouts |
26-
| **New Article** | `docs/posts/{YYYY}/` | Follow naming: `YYYY-MM-DD-slug.md` |
27-
| **Static Assets** | `docs/public/img/` | Reference as `/img/...` in MD |
28-
| **AI Skills** | `.claude/skills/` | Tool definitions & logic |
26+
| **Site Config** | `docs/.vitepress/config.mts` | Nav, Sidebar, SEO, Mermaid plugin |
27+
| **Global Styles** | `docs/.vitepress/theme/custom.css` | Academic Blue (#3B82F6), 1.8x line-height |
28+
| **New Article** | `docs/posts/{category}/` | MANDATORY: `YYYY-MM-DD-slug.md`, frontmatter validation |
29+
| **Images (Legacy)** | `docs/public/img/` | Reference as `/img/...`. BEING MIGRATED to `/images/YYYY/` |
30+
| **Images (New)** | `docs/public/images/2025/` | Year-based organization for long-term scalability |
31+
| **AI Skills** | `.claude/skills/{skill-name}/SKILL.md` | 16 atomic modules for content production |
2932
| **CI/CD** | `.github/workflows/deploy.yml` | Build & Deploy to GH Pages |
3033

34+
## SHARED RESOURCES
35+
| Resource | Purpose | Dependents |
36+
|----------|---------|------------|
37+
| `docs/.vitepress/config.mts` | Central config: nav, sidebar, Mermaid plugin | All pages |
38+
| `docs/.vitepress/theme/custom.css` | Global styles: Academic Blue, typography | All pages |
39+
| `.claude/skills/` | Reusable AI logic for content workflow | Claude Code tool |
40+
3141
## CONVENTIONS
32-
- **Frontmatter**: MANDATORY. Must include `title`, `date`, `categories` (from 5 allowed), `tags`.
33-
- **Links**: Use relative paths for internal links. `ignoreDeadLinks: false` enforces validity.
34-
- **Images**: Place in `docs/public/img/`. Reference via absolute path `/img/filename.png` in Markdown.
35-
- **Components**: Use VitePress containers (`:::info`) over raw HTML.
36-
- **Colors**: "Academic Blue" (`#3B82F6`) is the primary theme color.
42+
- **Writing Style**: Simple explanations for complex concepts. No jargon overload.
43+
- **Article Ordering**: Ascending chronological (oldest first) in categories & sidebar. Homepage uses reverse order.
44+
- **Frontmatter**: MANDATORY. `title`, `date`, `categories` (from 5 allowed), `tags`, `difficulty`, `summary`.
45+
- **Links**: Relative paths. `ignoreDeadLinks: false` enforces validity.
46+
- **Images**: TRANSITION PERIOD. Legacy in `public/img/`, new in `public/images/YYYY/`. Reference as `/img/...` or `/images/YYYY/...`.
47+
- **Containers**: Use `:::info`, `:::warning`, `:::tip` over raw HTML.
48+
- **Academic Blue**: `#3B82F6` (primary theme color).
3749

3850
## ANTI-PATTERNS (THIS PROJECT)
39-
- **Do NOT** place images in root `/img/`. Use `docs/public/img/`.
40-
- **Do NOT** create posts outside `docs/posts/YYYY/`.
41-
- **Do NOT** modify `package.json` scripts without updating `docs/SKILLS-GUIDE.md`.
42-
- **Do NOT** use `Makefile`. Use `npm scripts`.
51+
- **Do NOT** place images in root `/img/`. Use `docs/public/img/` or `docs/public/images/YYYY/`.
52+
- **Do NOT** create posts outside `docs/posts/{category}/`. No flat structure.
53+
- **Do NOT** modify `package.json` without updating `docs/SKILLS-GUIDE.md`.
54+
- **Do NOT** use `Makefile`. All ops via `npm scripts`.
55+
- **Do NOT** skip frontmatter. Build WILL fail.
56+
- **Do NOT** use absolute file paths in content.
57+
- **Do NOT** use raw HTML (`<img>`, `<div>`). Use Markdown/VitePress containers.
58+
59+
## CATEGORIES (5 ALLOWED)
60+
1. `agent-basics` — LLM Agent concepts, architecture, mechanisms
61+
2. `coding-agent` — Claude Code, OpenCode usage guides
62+
3. `research-cases` — Real applications in literature/data/writing
63+
4. `tools-comparison` — Agent tool evaluations
64+
5. `insights` — Experience summaries, lessons learned
4365

4466
## COMMANDS
4567
```bash
46-
npm run dev # Start local dev server (http://localhost:5173)
68+
npm run dev # Dev server (http://localhost:5173)
4769
npm run build # Production build -> docs/.vitepress/dist
4870
npm run preview # Preview production build
4971
```
5072

51-
## KNOWN ISSUES
52-
- `scripts/new-post.js` is missing (referenced in `package.json`).
53-
- `docs/index.md` has broken link to 2025 posts (actual: 2026).
54-
- Redundant `img/` directory in root (cleanup needed).
73+
## NOTES
74+
- **Scripts directory**: `package.json` references `scripts/new-post.js` but directory doesn't exist. Use AI Skills instead.
75+
- **Image path migration**: Active transition from `img/` to `images/YYYY/`. Update references gradually.

‎CLAUDE.md‎

Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
1+
# CLAUDE.md - 项目索引文档
2+
3+
> 本文件由架构扫描自动生成，供 AI 助手快速理解项目全貌。人类开发者亦可作为项目导航参考。
4+
5+
## 变更记录 (Changelog)
6+
7+
| 日期 | 操作 | 说明 |
8+
|------|------|------|
9+
| 2026-02-14 | 增量更新 | 文章目录结构迁移（按分类组织）、新增 5 篇 Agent 基础文章、Skills 增至 14 个、侧边栏改为分类展示 |
10+
| 2026-02-13 | 初始创建 | 首次全仓扫描，覆盖率 100% |
11+
12+
---
13+
14+
## 项目愿景
15+
16+
一个专注于分享 **Coding Agent（尤其是 LLM Coding Agent）在学术科研中的应用经验** 的技术博客。基于 VitePress 构建，部署于 GitHub Pages。目标受众为学术研究者和 AI 工具使用者。
17+
18+
- **在线地址**: https://hjnnjh.github.io/Agents-are-the-future-of-academic-research/
19+
- **作者**: [@hjnnjh](https://github.com/hjnnjh)
20+
- **许可**: 代码 MIT / 内容 CC BY-NC-SA 4.0
21+
22+
---
23+
24+
## 架构总览
25+
26+
本项目是一个**单模块 VitePress 静态博客站点**，无后端、无数据库、无微服务拆分。
27+
28+
| 层次 | 技术 | 说明 |
29+
|------|------|------|
30+
| 静态站点生成 | VitePress 1.5+ | 基于 Vite，极速构建 |
31+
| 前端框架 | Vue 3.4+ | VitePress 内置 |
32+
| 语言 | TypeScript / CSS / Markdown | 配置用 TS，内容用 MD |
33+
| 图表 | Mermaid 11.x + vitepress-plugin-mermaid | 流程图/架构图 |
34+
| 数学公式 | markdown-it-mathjax3 (KaTeX) | LaTeX 公式渲染 |
35+
| 部署 | GitHub Actions -> GitHub Pages | push main 自动部署 |
36+
| AI 工具链 | 14 个 Claude Code Skills | 写作/图表/质量/维护/审查 |
37+
38+
---
39+
40+
## 模块结构图
41+
42+
本项目为单模块结构，以下为目录拓扑：
43+
44+
```mermaid
45+
graph TD
46+
ROOT["(根) Agents-are-the-future-of-academic-research"] --> DOCS["docs/"]
47+
ROOT --> GITHUB[".github/"]
48+
ROOT --> CLAUDE_DIR[".claude/"]
49+
50+
DOCS --> VP[".vitepress/"]
51+
DOCS --> POSTS["posts/"]
52+
DOCS --> CATEGORIES["categories/"]
53+
DOCS --> ABOUT["about/"]
54+
DOCS --> PUBLIC["public/"]
55+
DOCS --> SKILLS_GUIDE["SKILLS-GUIDE.md"]
56+
DOCS --> INDEX_MD["index.md (首页)"]
57+
58+
VP --> CONFIG["config.mts (站点配置)"]
59+
VP --> THEME["theme/"]
60+
THEME --> THEME_INDEX["index.ts"]
61+
THEME --> CUSTOM_CSS["custom.css"]
62+
63+
POSTS --> AB["agent-basics/ (5 篇)"]
64+
POSTS --> CA["coding-agent/ (1 篇)"]
65+
66+
CATEGORIES --> CAT1["agent-basics.md"]
67+
CATEGORIES --> CAT2["coding-agent.md"]
68+
CATEGORIES --> CAT3["research-cases.md"]
69+
CATEGORIES --> CAT4["tools-comparison.md"]
70+
CATEGORIES --> CAT5["insights.md"]
71+
72+
ABOUT --> ABOUT_INDEX["index.md"]
73+
74+
PUBLIC --> IMG["img/"]
75+
76+
GITHUB --> WORKFLOWS["workflows/"]
77+
WORKFLOWS --> DEPLOY["deploy.yml"]
78+
79+
CLAUDE_DIR --> SKILLS[".claude/skills/ (14 个)"]
80+
81+
click SKILLS_GUIDE "./docs/SKILLS-GUIDE.md" "Skills 使用指南"
82+
```
83+
84+
---
85+
86+
## 模块索引
87+
88+
本项目为单体博客，无独立子模块。以下按功能区域列出：
89+
90+
| 功能区域 | 路径 | 说明 |
91+
|----------|------|------|
92+
| 站点配置 | `docs/.vitepress/config.mts` | VitePress 核心配置（导航/侧边栏/Markdown/SEO/Mermaid） |
93+
| 自定义主题 | `docs/.vitepress/theme/` | 扩展默认主题 + 学术蓝配色 CSS |
94+
| 首页 | `docs/index.md` | Hero 布局 + Features 卡片 |
95+
| 博客文章 | `docs/posts/{category}/` | 按分类目录组织，含 frontmatter 元数据（共 6 篇） |
96+
| 分类页 | `docs/categories/` | 5 大分类的索引页 |
97+
| 关于页 | `docs/about/index.md` | 站点介绍与联系方式 |
98+
| Skills 指南 | `docs/SKILLS-GUIDE.md` | 14 个 Claude Code Skills 的使用文档 |
99+
| 静态资源 | `docs/public/img/` | Hero 图片（PNG） |
100+
| CI/CD | `.github/workflows/deploy.yml` | GitHub Actions 自动构建部署 |
101+
| Claude Skills | `.claude/skills/` | 14 个 SKILL.md 定义文件 |
102+
103+
---
104+
105+
## 运行与开发
106+
107+
### 环境要求
108+
109+
- Node.js >= 18.0.0 (推荐 20.x LTS)
110+
- npm >= 9.0.0
111+
112+
### 常用命令
113+
114+
```bash
115+
# 安装依赖
116+
npm install
117+
118+
# 本地开发（热更新）
119+
npm run dev # -> http://localhost:5173
120+
121+
# 生产构建
122+
npm run build # 输出到 docs/.vitepress/dist/
123+
124+
# 预览构建结果
125+
npm run preview # -> http://localhost:4173
126+
127+
# 创建新文章（脚本未实现）
128+
npm run new-post # 引用 scripts/new-post.js，当前文件不存在
129+
```
130+
131+
### 部署
132+
133+
- **自动部署**: 推送到 `main` 分支后，GitHub Actions 自动构建并部署到 GitHub Pages
134+
- **base 路径**: `/Agents-are-the-future-of-academic-research/`
135+
- **部署配置**: `.github/workflows/deploy.yml`
136+
137+
---
138+
139+
## 内容分类体系
140+
141+
博客内容分为 5 大类：
142+
143+
1. **Agent 基础** (`/categories/agent-basics`) - LLM Agent 核心概念与架构 [5 篇]
144+
2. **Coding Agent 实践** (`/categories/coding-agent`) - Claude Code/OpenCode 深度技巧 [1 篇]
145+
3. **学术科研案例** (`/categories/research-cases`) - 文献/数据/论文场景应用 [待填充]
146+
4. **工具对比评测** (`/categories/tools-comparison`) - 横向对比与选型 [待填充]
147+
5. **经验心得分享** (`/categories/insights`) - 踩坑记录与效率技巧 [待填充]
148+
149+
### 已发布文章清单
150+
151+
| 分类 | 文章 | 日期 |
152+
|------|------|------|
153+
| Agent 基础 | LLM Agent 简介 | 2026-02-13 |
154+
| Agent 基础 | Agent 的记忆系统 | 2026-02-14 |
155+
| Agent 基础 | 上下文工程 | 2026-02-15 |
156+
| Agent 基础 | 多 Agent 协作 | 2026-02-16 |
157+
| Agent 基础 | Agent 评估 | 2026-02-17 |
158+
| Coding Agent 实践 | Agent Skills 使用入门 | 2026-02-10 |
159+
160+
---
161+
162+
## 文章写作规范
163+
164+
### 写作风格
165+
166+
- **深入浅出，不给读者带去认知负担**：用通俗易懂的语言解释复杂概念，避免堆砌术语，确保不同背景的读者都能顺畅阅读。
167+
168+
### 文章排序规则
169+
170+
- **按日期升序排列**：在分类页（`docs/categories/*.md`）和侧边栏（`config.mts` 的 `sidebar`）中，文章按发布日期从早到晚排列，新文章放在列表底部。首页"最新文章"列表除外，仍按倒序展示。
171+
172+
### Frontmatter 必填字段
173+
174+
```yaml
175+
---
176+
title: "文章标题"
177+
date: YYYY-MM-DD
178+
author: "作者名"
179+
categories:
180+
- coding-agent # 从 5 大分类选择
181+
tags:
182+
- claude-code
183+
- tutorial
184+
difficulty: beginner # beginner / intermediate / advanced
185+
summary: "50-200 字摘要"
186+
featured: false # 是否精选
187+
---
188+
```
189+
190+
### 文件命名
191+
192+
`docs/posts/{category}/YYYY-MM-DD-slug.md`
193+
194+
### 支持的 Markdown 增强
195+
196+
- LaTeX 数学公式（行内 `$...$`，独立块 `$$...$$`）
197+
- Mermaid 流程图/架构图（` ```mermaid ` 代码块）
198+
- 代码块行号与语法高亮（双主题：github-light / github-dark）
199+
- VitePress 自定义容器（`:::tip`、`:::warning`、`:::danger`、`:::info`）
200+
- 脚注（markdown-it-footnote）
201+
- 任务列表（markdown-it-task-lists）
202+
203+
---
204+
205+
## 测试策略
206+
207+
本项目当前**无自动化测试**。验证方式：
208+
209+
- `npm run build` 构建成功即为基本验证
210+
- `ignoreDeadLinks: false` 配置会在构建时检查死链
211+
- 手动浏览器验证各页面功能
212+
213+
---
214+
215+
## 编码规范
216+
217+
- TypeScript 配置文件使用 `.mts` 后缀
218+
- CSS 使用 VitePress 主题变量（`--vp-c-*`），支持深色/浅色模式
219+
- Markdown 标题最多 4 级（H1-H4）
220+
- 代码块必须标注语言
221+
- 内部链接使用相对路径
222+
223+
---
224+
225+
## AI 使用指引
226+
227+
### 修改站点配置
228+
229+
核心文件: `docs/.vitepress/config.mts`
230+
- 导航菜单: `themeConfig.nav`
231+
- 侧边栏: `themeConfig.sidebar`（按分类分组展示，非按年份）
232+
- 新增文章后需同步更新侧边栏配置
233+
234+
### 新增文章
235+
236+
1. 在 `docs/posts/{category}/` 下创建 `YYYY-MM-DD-slug.md`（category 为文章所属分类，如 `agent-basics`、`coding-agent`）
237+
2. 填写完整 frontmatter
238+
3. 在 `config.mts` 的 `sidebar['/posts/']` 对应分类组中添加条目（按日期升序，新文章放在该组末尾）
239+
4. 在对应 `docs/categories/*.md` 中添加文章链接（按日期升序）
240+
5. 在 `docs/index.md` 的"最新文章"列表顶部添加条目（按日期倒序）
241+
242+
### 修改主题样式
243+
244+
文件: `docs/.vitepress/theme/custom.css`
245+
- 主色调为"学术蓝"（`#3B82F6`）
246+
- 支持深色模式变量覆盖
247+
248+
### 已知问题
249+
250+
1. `scripts/new-post.js` 在 `package.json` 中引用但文件不存在
251+
2. 3 个分类页（research-cases, tools-comparison, insights）内容为空占位
252+
253+
### Claude Code Skills
254+
255+
项目集成了 14 个 Claude Code Skills，定义在 `.claude/skills/` 目录下：
256+
257+
| 类别 | Skills |
258+
|------|--------|
259+
| 写作与内容 | markdown-tools, content-research-writer, prompt-optimizer, beautiful-prose |
260+
| 技术工具 | mermaid-tools, changelog-generator, docs-cleaner |
261+
| 设计展示 | ui-designer, cli-demo-generator |
262+
| 文档与质量 | pdf-creator, fact-checker, skill-reviewer |
263+
| 审查（只读） | content-reviewer, markdown-reviewer |
264+
265+
详细使用指南见 `docs/SKILLS-GUIDE.md`。

0 commit comments

Comments
 (0)