docs: sync repository documentation facts

AGENTS.md

@@ -33,16 +33,19 @@
 # 1. 拉取最新代码
 git pull --rebase origin develop
 
-# 2. 运行 lint 检查
+# 2. 初始化外部仓库指针
+git submodule update --init --recursive
+
+# 3. 运行 lint 检查
 make lint
 
-# 3. 执行修改任务
+# 4. 执行修改任务
 # ...
 
-# 4. 再次 lint 验证
+# 5. 再次 lint 验证
 make lint
 
-# 5. 提交变更
+# 6. 提交变更
 git add -A
 git commit -m "feat|fix|docs|chore: scope - summary"
 git push origin develop
@@ -54,7 +57,7 @@ git push origin develop
 
 ### 环境要求
 - Node.js 16+（用于 markdownlint-cli）
-- Python 3.8+（用于 prompts-library 工具）
+- Python 3.8+（用于 prompts-library 工具与备份脚本）
 - Git
 
 ### 核心命令
@@ -63,9 +66,14 @@ git push origin develop
 |:---|:---|:---|
 | `make help` | 列出所有 Make 目标 | 无 |
 | `make lint` | 校验全仓库 Markdown | 需安装 markdownlint-cli |
+| `git submodule update --init --recursive` | 初始化外部 Git 仓库指针 | Git |
 | `bash assets/repos/backups/一键备份.sh` | 创建完整项目备份 | 无 |
 | `python3 assets/repos/backups/快速备份.py` | Python 版备份脚本 | Python 3.8+ |
-| `cd assets/repos/prompts-library && python3 main.py` | 提示词格式转换 | pandas, openpyxl, PyYAML |
+| `cd assets/repos/prompts-library && python3 main.py` | 提示词格式转换 | `pip install -r assets/repos/prompts-library/requirements.txt` |
+
+### Python 依赖来源
+- prompts-library 主入口依赖：`assets/repos/prompts-library/requirements.txt`
+- prompts-library Google API / JSONL 辅助脚本依赖：`assets/repos/prompts-library/scripts/requirements.txt`
 
 ### prompts-library 支持的转换模式
 1. Excel → Docs：将 Excel 工作簿转换为 Markdown 文档目录
@@ -144,7 +152,7 @@ git push origin develop
 │   │       └── AGENTS.md        # Codex/Agent 指南（本目录）
 │   ├── documents/               # 文档库
 │   │   ├── principles/          # 原则与思想（fundamentals + philosophy）
-│   │   │   ├── fundamentals/    # 原 00-基础指南
+│   │   │   ├── fundamentals/    # 基础原则、问题求解、工程范式与代码质量
 │   │   │   └── philosophy/      # 原 05-哲学与方法论
 │   │   ├── guides/              # 入门与方法（getting-started + playbook）
 │   │   │   ├── getting-started/ # 原 01-入门指南
@@ -190,8 +198,12 @@ git push origin develop
 ### 关键入口文件
 - `README.md` - 项目主文档，面向人类开发者
 - `AGENTS.md` - AI Agent 操作手册（本文件）
+- `.github/lint_config.json` - markdownlint 规则，供 `make lint` 与 CI 共用
+- `.github/workflows/ci.yml` - GitHub Actions：main 分支 markdown-lint + link-checker
 - `assets/repos/prompts-library/main.py` - 提示词转换工具入口
 - `assets/repos/backups/一键备份.sh` - 备份脚本入口
+- `assets/documents/principles/fundamentals/问题求解能力.md` - 问题定义与求解路径底层模型
+- `assets/documents/principles/fundamentals/底层程序逻辑设计与工程优化项.md` - 底层程序逻辑与工程优化检查项
 - `assets/skills/tmux-autopilot/` - tmux 自动化操控技能（基于 oh-my-tmux，含 capture-pane/send-keys/蜂群巡检脚本）
 - `assets/skills/sop-generator/` - SOP 生成与规范化技能（输入资料/需求 -> 标准 SOP）
 
@@ -202,8 +214,9 @@ git push origin develop
 | 问题 | 原因 | 修复 |
 |:---|:---|:---|
 | `make lint` 失败 | 未安装 markdownlint-cli | `npm install -g markdownlint-cli` |
-| prompts-library 报错 | 缺少 Python 依赖 | `pip install pandas openpyxl PyYAML rich InquirerPy` |
-| CI markdown-lint 失败 | `.github/lint_config.json` 缺失 | TODO：新增 `.github/lint_config.json` 或调整 `.github/workflows/ci.yml` 的 lint 命令（需任务明确授权） |
+| prompts-library 报错 | 缺少 Python 依赖 | `pip install -r assets/repos/prompts-library/requirements.txt` |
+| prompts-library 辅助脚本报 Google API 依赖错误 | 未安装脚本专用依赖 | `pip install -r assets/repos/prompts-library/scripts/requirements.txt` |
+| CI markdown-lint 失败 | Markdown 规则违规或本地未按 `.github/lint_config.json` 校验 | 运行 `make lint`，按输出修复对应 Markdown |
 | CI link-checker 失败 | 文档中存在失效链接 | 检查并修复 Markdown 中的链接 |
 | 备份脚本权限不足 | Shell 脚本无执行权限 | `chmod +x assets/repos/backups/一键备份.sh` |
 

README.md

@@ -105,6 +105,56 @@
 
 </details>
 
+<details>
+<summary><strong>🛠️ 仓库维护与验证</strong></summary>
+
+## 🛠️ 仓库维护与验证
+
+本仓库是文档与资源型项目，不提供可验证的 dev server、Docker/K8s 部署入口或固定服务端口。当前可验证的自动化入口来自 `Makefile`、`.github/workflows/ci.yml`、`assets/repos/prompts-library/` 与 `assets/repos/backups/`。
+
+### 环境要求
+
+- Git：版本控制与 submodule 初始化
+- Node.js 16+：运行 `markdownlint-cli`，与 GitHub Actions 中的 `setup-node@v3` 配置一致
+- Python 3.8+：运行 prompts-library 与备份脚本
+
+### 初始化
+
+```bash
+git submodule update --init --recursive
+pip install -r assets/repos/prompts-library/requirements.txt
+```
+
+如需运行 prompts-library 的 Google API / JSONL 辅助脚本，再安装脚本依赖：
+
+```bash
+pip install -r assets/repos/prompts-library/scripts/requirements.txt
+```
+
+### 常用命令
+
+| 目的 | 命令 | 来源 |
+|:---|:---|:---|
+| 查看 Make 任务 | `make help` | `Makefile` |
+| 全仓 Markdown lint | `make lint` | `Makefile` + `.github/lint_config.json` |
+| 提示词格式转换 | `cd assets/repos/prompts-library && python3 main.py` | `assets/repos/prompts-library/main.py` |
+| 完整备份 | `bash assets/repos/backups/一键备份.sh` | `assets/repos/backups/README.md` |
+| Python 备份 | `python3 assets/repos/backups/快速备份.py` | `assets/repos/backups/README.md` |
+| Skill 严格校验示例 | `assets/skills/auto-skill/scripts/validate-skill.sh assets/skills/auto-skill --strict` | `assets/skills/auto-skill/scripts/validate-skill.sh` |
+
+### 配置与 CI
+
+- Markdown lint 配置：`.github/lint_config.json`
+- CI 配置：`.github/workflows/ci.yml`，在 `main` 分支的 push / pull_request 上运行 markdown-lint 与 link-checker
+- Codex 配置基线：`assets/config/.codex/config.toml`
+- Submodule 来源：`.gitmodules`
+
+### 部署
+
+TODO：仓库内没有发现 Dockerfile、docker-compose.yml、K8s/Helm 部署入口或可验证服务端口；如后续新增部署方式，需要同步本节。
+
+</details>
+
 <details>
 <summary><strong>🧪 实验性方法</strong></summary>
 
@@ -331,7 +381,7 @@
 │   │       └── AGENTS.md        # Codex/Agent 指南（本目录）
 │   ├── documents/               # 文档库
 │   │   ├── principles/          # 原则与思想（fundamentals + philosophy）
-│   │   │   ├── fundamentals/    # 原 00-基础指南
+│   │   │   ├── fundamentals/    # 基础原则、问题求解、工程范式与代码质量
 │   │   │   └── philosophy/      # 原 05-哲学与方法论
 │   │   ├── guides/              # 入门与方法（getting-started + playbook）
 │   │   │   ├── getting-started/ # 原 01-入门指南
@@ -462,7 +512,7 @@ graph TB
   subgraph infra_layer[基础设施与横切能力层]
     git[Git 版本控制] --> orchestrator
     backups[assets/repos/backups/一键备份.sh · assets/repos/backups/快速备份.py] --> artifacts_md
-    deps[requirements.txt · scripts/requirements.txt] --> orchestrator
+    deps[assets/repos/prompts-library/requirements.txt · assets/repos/prompts-library/scripts/requirements.txt] --> orchestrator
     config[assets/repos/prompts-library/scripts/config.yaml] --> orchestrator
     monitor[预留：日志与监控] --> orchestrator
   end

assets/repos/backups/README.md

@@ -13,7 +13,7 @@
 ## 文件结构
 
 ```
-backups/
+assets/repos/backups/
 ├── 快速备份.py    # 核心备份引擎
 ├── 一键备份.sh    # Shell 启动脚本
 └── README.md      # 本文档
@@ -23,28 +23,28 @@ backups/
 
 ```bash
 # 方式一：Shell 脚本（推荐）
-bash backups/一键备份.sh
+bash assets/repos/backups/一键备份.sh
 
 # 方式二：直接运行 Python
-python3 backups/快速备份.py
+python3 assets/repos/backups/快速备份.py
 
 # 指定输出文件
-python3 backups/快速备份.py -o my_backup.tar.gz
+python3 assets/repos/backups/快速备份.py -o my_backup.tar.gz
 
 # 指定项目目录
-python3 backups/快速备份.py -p /path/to/project
+python3 assets/repos/backups/快速备份.py -p /path/to/project
 ```
 
 ## 输出位置
 
-默认输出到 `backups/gz/备份_YYYYMMDD_HHMMSS.tar.gz`
+默认输出到 `assets/repos/backups/gz/备份_YYYYMMDD_HHMMSS.tar.gz`
 
 ## 参数说明
 
 | 参数 | 说明 | 默认值 |
 |------|------|--------|
 | `-p, --project` | 项目根目录 | 当前目录 |
-| `-o, --output` | 输出文件路径 | `backups/gz/备份_时间戳.tar.gz` |
+| `-o, --output` | 输出文件路径 | `assets/repos/backups/gz/备份_时间戳.tar.gz` |
 | `-g, --gitignore` | gitignore 文件路径 | `.gitignore` |
 
 ## 依赖