📝 调整文档分层并补充 workflow 运行模型

tests/template_defaults_test.sh

@@ -55,6 +55,19 @@ test_workflow_docs_and_links_use_actual_paths() {
     ! rg -q '/\\.github/workflows/' "${release_workflow}" || fail "release workflow should not link to .github/workflows"
 }
 
+test_workflow_doc_describes_workspace_architecture() {
+    local file
+
+    file="${REPO_ROOT}/WORKFLOW.md"
+
+    grep -q 'Git bare 镜像 + 工作副本' "${file}" || fail "WORKFLOW.md should explicitly describe the bare mirror plus worktree-style model"
+    grep -q '共享仓库缓存' "${file}" || fail "WORKFLOW.md should describe the shared repository cache model"
+    grep -q '独立工作副本' "${file}" || fail "WORKFLOW.md should describe isolated per-job work copies"
+    grep -q '任务结束后' "${file}" || fail "WORKFLOW.md should mention cleanup after workflow completion"
+    ! rg -q 'bootstrap_workspace\.sh' "${file}" || fail "WORKFLOW.md should describe architecture rather than helper implementation"
+    ! rg -q '/data/git-mirrors|/home/workspace/jobs' "${file}" || fail "WORKFLOW.md should avoid implementation-specific workspace paths"
+}
+
 test_presets_do_not_mount_check_crlf_helper() {
     ! rg -q 'check_crlf\.sh:/data/check_crlf\.sh:ro' "${REPO_ROOT}/docker-runner/presets" || fail "preset compose files should not mount check_crlf helper into containers"
 }
@@ -70,15 +83,29 @@ test_runner_data_is_gitignored() {
     done
 }
 
-test_readme_is_navigation_focused() {
+test_readme_has_project_intro_and_navigation() {
     local file
 
     file="${REPO_ROOT}/README.md"
 
-    grep -q '^## 🚀 快速开始$' "${file}" || fail "README.md should provide a quick start section"
+    grep -q '^## 📖 项目简介$' "${file}" || fail "README.md should provide a project intro section"
+    grep -q '^## 📂 文档导航$' "${file}" || fail "README.md should provide a document navigation section"
     grep -q '\[DEPLOYMENT.md\](\./DEPLOYMENT.md)' "${file}" || fail "README.md should link to DEPLOYMENT.md"
     grep -q '\[WORKFLOW.md\](\./WORKFLOW.md)' "${file}" || fail "README.md should link to WORKFLOW.md"
-    grep -q 'cp \.env\.example \.env' "${file}" || fail "README.md quick start should mention copying .env.example"
+    grep -q '具体部署步骤.*\[DEPLOYMENT.md\](\./DEPLOYMENT.md)' "${file}" || fail "README.md should delegate deployment details to DEPLOYMENT.md"
+    ! rg -q '^## 🚀 快速提示$' "${file}" || fail "README.md should not carry concrete deployment tip sections"
+    ! rg -q '^## ⚙️ 当前默认行为$' "${file}" || fail "README.md should not carry default behavior details"
+}
+
+test_deployment_doc_stays_runner_focused() {
+    local file
+
+    file="${REPO_ROOT}/DEPLOYMENT.md"
+
+    ! rg -q '^## ⚙️ 默认行为$' "${file}" || fail "DEPLOYMENT.md should not carry generic default behavior sections"
+    ! rg -q '/data/git-mirrors/<owner>/<repo>\.git' "${file}" || fail "DEPLOYMENT.md should not document workflow mirror paths"
+    ! rg -q '/home/workspace/jobs/' "${file}" || fail "DEPLOYMENT.md should not document workflow temp workspace paths"
+    ! rg -q 'bootstrap_workspace\.sh' "${file}" || fail "DEPLOYMENT.md should stay focused on runner deployment, not workflow helpers"
 }
 
 test_presets_define_expected_hostname() {
@@ -104,9 +131,11 @@ test_preset_compose_uses_env_for_instance
 test_workflows_do_not_hardcode_company_server
 test_stats_workflow_uses_workflow_secret_consistently
 test_workflow_docs_and_links_use_actual_paths
+test_workflow_doc_describes_workspace_architecture
 test_presets_do_not_mount_check_crlf_helper
 test_runner_data_is_gitignored
-test_readme_is_navigation_focused
+test_readme_has_project_intro_and_navigation
+test_deployment_doc_stays_runner_focused
 test_presets_define_expected_hostname
 test_preset_env_examples_exist
 

tests/workspace_helper_test.sh

@@ -164,13 +164,6 @@ test_presets_do_not_mount_workspace_helper() {
     fi
 }
 
-test_docs_mention_git_mirrors() {
-    if ! grep -q "/data/git-mirrors" "${REPO_ROOT}/DEPLOYMENT.md"; then
-        echo "FAIL: deployment docs should describe persistent git mirrors" >&2
-        exit 1
-    fi
-}
-
 test_repo_path_layout
 test_job_identity_prefers_run_metadata
 test_sanitize_job_name
@@ -181,6 +174,5 @@ test_register_default_capacity_is_four
 test_changelog_workflow_uses_workspace_helper
 test_stats_workflow_uses_workspace_helper
 test_presets_do_not_mount_workspace_helper
-test_docs_mention_git_mirrors
 
 echo "workspace_helper_test.sh: PASS"