project-blueprint: Instructions file for Codex

Project Blueprint 项目开发规范 (AGENTS.md)

AI 编程助手的强制开发规范。v1.0 | 2026-08-01 AI 工具: Trae | 加载: always_applied

---

一、项目身份

• 项目: Project Blueprint — 为新项目一键建立完整 AI 编程规范体系（AGENTS.md + 文档骨架 + CI/CD + 测试制度 + Git 规范）的开源 AI Agent 技能包。
• 形态: 纯 Markdown 项目，无代码、无构建、无测试、无运行依赖。核心逻辑为 SKILL.md（7 Step 流程），配套 references/ 知识库。
• 技术栈: Markdown (SKILL.md 格式) + 70+ 组件知识库 + MCP 工具知识库 + WebSearch 联网回退
• 版本: v1.7.1（语义化版本，tag 发布）
• 仓库: GitHub origin = https://github.com/shuguang1994/project-blueprint / Gitee gitee = https://gitee.com/shuguang1994/project-blueprint
• 作者: 曙光 (shuguang1994) | License: MIT
• 安装: npx skills add shuguang1994/project-blueprint（国际）/ npx skills add https://gitee.com/shuguang1994/project-blueprint.git（国内）/ dsh plugin --profile web add 'github:shuguang1994/project-blueprint'（DeepSeek Harness）

二、常用命令

# 本仓库无编译/测试命令，常用操作为 Git 双远程推送：
git add <files>                                # 暂存（按文件逐一添加，勿 git add -A）
git commit -m "<type>(<scope>): <description>" # 提交
git push origin main                           # 推送 GitHub
git push gitee main --tags                     # 推送 Gitee 镜像 + 版本标签
git fetch origin && git fetch gitee            # 同步双远程
git revert <commit>                            # 线上问题回滚

# 技能安装/更新（验证对外文档描述一致性时参考）：
npx skills update project-blueprint

# DSH 插件包同步（修改根 SKILL.md / references/ 后，发版前运行）：
node dsh-plugin/scripts/sync-skill.mjs

三、Boundaries

Allowed: SKILL.md、references/、README.md、README_CN.md、CHANGELOG.md、PROJECT_STATUS.md、AGENTS.md、docs/、.gitignore、dsh-plugin/（不含 dsh-plugin/skills/，由同步脚本生成）

Ask First:

• 版本号升级（vX.Y.Z）或破坏性变更（如 Step 流程重构、文件重命名）
• 修改 SKILL.md 中的流程步骤、触发条件、输出格式约定
• 新增/删除 references/ 下的参考文件
• 双远程仓库的 git 操作（push/force/tag）

Never Touch: .git/、LICENSE（协议条款）、证书/密钥、任何 .env 文件、node_modules/

四、强制规范

4.1 文档规范

✅ README.md 与 README_CN.md 内容保持同步（中英对照，同一特性两处都要更新）
✅ 新增特性同时更新：README / README_CN / CHANGELOG / PROJECT_STATUS
✅ 初始化项目时生成 CHANGELOG.md（[Unreleased] 占位，首次发版后转版本号记录）
✅ 文件名中英双语标注，按 A/B/C/D/E 五级分类存放
✅ 代码块必须闭合（开闭围栏语言标记一致），防止后续章节被误渲染
✅ 对外文档中的数字保持一致（如框架数量 15、组件数量 70+）
✅ 新增知识库条目后同步更新 README 技术栈覆盖表