Imported from yuanshenjian-cn/yuanshenjian-cn (
AGENTS.md). Install upstream withnpx skills add yuanshenjian-cn/yuanshenjian-cn. Copyright stays with the author.
AGENTS.md — 个人博客仓库开发规范
本仓库以根目录为统一 workspace。日常开发、联调、AI 助手会话默认都在根目录工作。 每个子工程都有独立的 AGENTS.md,开始任何子工程内的代码改动前,必须先阅读对应文件并按其规范执行。
通用规则
- 回复语言:使用中文与用户交流。
子工程规范强制约束(最高优先级)
该约束高于本文件中其他章节。任何冲突以子工程的
AGENTS.md为准。
触发条件 → 必读文件
| 当任务涉及… | 动手前必须先阅读 |
|---|---|
site/** 的任何文件(前端组件、页面、样式、类型、测试) |
site/AGENTS.md |
core-service/** 的任何文件(API、service、模型、迁移、配置) |
core-service/AGENTS.md |
admin-console/** 的任何文件 |
(暂沿用根目录通用规范) |
content/** 的内容文件 |
见下方「内容规范」一节 |
工作流强制要求
- 先读后写:修改子工程文件前,必须先读取并遵守对应
AGENTS.md,不得凭记忆或假设动手。 - 跨子工程改动:一次任务涉及多个子工程时,每个子工程的
AGENTS.md都必须遵守,不得用一份覆盖另一份。 - 冲突解决:根目录与子工程规范冲突时,子工程
AGENTS.md优先;本文件只承担跨工程协作、根级命令、Git 等通用约束。 - 新增子工程:若新增带独立技术栈的子目录,应同步建立其
AGENTS.md,并在下方表格注册。 - 修改
site/**前端代码时:必须同时参考site/AGENTS.md中的组件命名、目录边界与前端质量门禁。
仓库结构与子目录职责
| 目录 | 职责 | 子工程规范 |
|---|---|---|
site/ |
Next.js 15 公开主站前端(博客展示、评论、AI 入口) | site/AGENTS.md |
admin-console/ |
Vite + React 独立管理后台 SPA(评论审核、数据概览) | 暂未独立,沿用根目录规范 |
core-service/ |
FastAPI 统一后端(公开 API + 管理 API) | core-service/AGENTS.md |
content/ |
Markdown / MDX 文章源(博客、AI 简报、投资简报) | — |
scripts/ |
构建辅助脚本(AI 数据生成、图片优化等) | — |
config/ |
仓库级公共配置 | — |
docs/ |
工程文档 | — |
.claude/ / .opencode/ |
AI 助手 skills、记忆、提示词配置 | — |
核心命令
所有日常开发与联调统一在仓库根目录通过 just 完成:
just start-site # 启动主站前端
just start-admin-console # 启动管理后台
just start-core-service # 启动后端服务(自动执行迁移)
just start-site-and-core-service # 主站 + 后端联调
just start-admin-console-and-core-service # 后台 + 后端联调
just start-all-services # 三端联调
just check-site # 主站 typecheck/lint/test
just check-admin-console # 管理后台 typecheck/build
just check-core-service # 后端 Ruff/mypy/pytest
just check # 全仓关键校验
just build-site # 主站构建
just build-site-prod # 主站完整生产构建
just preview-site # 预览主站构建产物
just run-core-migrations # 执行后端数据库迁移
just validate-content # 校验内容
内容(content/)规范
- 博客文章位于
content/blog/,AI 简报位于content/ai-briefings/YYYY/MM/,投资简报位于content/investment-briefings/YYYY/MM/ - 必需 frontmatter 字段:
title、date - 可选字段:
tags、published、brief - 修改内容后执行
just validate-content验证
环境变量
cp .env.example .env.local
各子工程的具体环境变量见对应子目录的 AGENTS.md 或 .env.example。
部署
- 平台:GitHub Pages + Cloudflare CDN
- 域名:yuanshenjian.cn
- 工作流:
.github/workflows/deploy-web-site.yml - 触发:推送到
main分支 - Node.js:20.x
Git 规则
- 禁止使用
--no-verify - force push 必须使用
--force-with-lease - 非用户明确要求,不主动提交 commit
- commit message 使用中文,遵循 Conventional Commits 格式
