@hunyed15/codecgc 0.1.6 → 0.1.8

package/scripts/install_codecgc.py

@@ -10,6 +10,7 @@ from typing import Any
 from codecgc_console_io import render_summary_block
 from codecgc_executor_registry import build_executor_registry
 from codecgc_executor_registry import resolve_python_command
+from codecgc_policy import load_policy
 from codecgc_routing_template import sync_workspace_routing_file
 from codecgc_runtime_paths import PACKAGE_ROOT
 from codecgc_runtime_paths import resolve_workspace_root
@@ -24,12 +25,16 @@ SETTINGS_PATH = CLAUDE_DIR / "settings.json"
 MCP_CONFIG_PATH = WORKSPACE / ".mcp.json"
 PROJECT_HOOK_PATH = HOOKS_DIR / "route-edit.ps1"
 PROJECT_ROUTING_PATH = WORKSPACE / "model-routing.yaml"
+EDIT_GUARDRAIL_MATCHER = "Edit|Write|MultiEdit"
+LEGACY_EDIT_GUARDRAIL_MATCHERS = {"Edit|Write"}
+PROJECT_ONBOARDING_RELATIVE_PATH = "codecgc/START_HERE.md"
+PROJECT_ONBOARDING_MARKER = "<!-- codecgc:onboarding:v1 -->"
 
 
 DEFAULT_HOOKS = {
     "PreToolUse": [
         {
-            "matcher": "Edit|Write",
+            "matcher": EDIT_GUARDRAIL_MATCHER,
             "hooks": [
                 {
                     "type": "command",
@@ -48,6 +53,22 @@ DEFAULT_ALLOWED_TOOLS = [
     "mcp__gemini__*",
 ]
 
+PROJECT_WORKFLOW_DIRS = [
+    "codecgc/features",
+    "codecgc/issues",
+    "codecgc/execution",
+    "codecgc/requirements",
+    "codecgc/architecture",
+    "codecgc/roadmap",
+    "codecgc/compound",
+    "codecgc/docs",
+    "codecgc/reference",
+    "codecgc/fixtures/features",
+    "codecgc/fixtures/issues",
+    "codecgc/fixtures/execution",
+    "codecgc/fixtures/roadmap",
+]
+
 
 def get_user_claude_root(override_root: str = "") -> Path:
     override = override_root.strip() or os.environ.get("CODECGC_USER_CLAUDE_DIR", "").strip()
@@ -86,6 +107,7 @@ def get_workspace_paths(override_workspace: str = "") -> dict[str, Path]:
         "hook_script": hooks_dir / "route-edit.ps1",
         "commands_dir": claude_dir / "commands",
         "routing_file": root / "model-routing.yaml",
+        "onboarding_file": root / PROJECT_ONBOARDING_RELATIVE_PATH,
     }
 
 
@@ -101,11 +123,122 @@ def load_text_file(path: Path) -> str:
     return path.read_text(encoding="utf-8")
 
 
+def ensure_workspace_workflow_dirs(workspace_root: Path) -> list[str]:
+    created_or_existing: list[str] = []
+    for relative_path in PROJECT_WORKFLOW_DIRS:
+        directory = workspace_root / relative_path
+        directory.mkdir(parents=True, exist_ok=True)
+        created_or_existing.append(str(directory))
+    return created_or_existing
+
+
+def workspace_workflow_dirs_ready(workspace_root: Path) -> bool:
+    return all((workspace_root / relative_path).is_dir() for relative_path in PROJECT_WORKFLOW_DIRS)
+
+
+def build_project_onboarding_text() -> str:
+    return f"""{PROJECT_ONBOARDING_MARKER}
+# CodeCGC Start Here
+
+This file is generated by `cgc-install` for this project. It is intentionally project-relative and should not contain machine-specific install paths.
+
+## First Run
+
+Inside Claude:
+
+```text
+/cgc-start
+/cgc-status
+/cgc-doctor
+/cgc 新增一个登录页面，放在 src/components/LoginForm.tsx
+```
+
+Outside Claude:
+
+```bash
+cgc-start
+cgc-status
+cgc-doctor
+cgc "新增一个登录页面，放在 src/components/LoginForm.tsx"
+```
+
+## What CodeCGC Owns
+
+- Claude owns orchestration, requirements, design notes, docs, review, acceptance, and workflow state.
+- Codex owns backend implementation and backend tests.
+- Gemini owns frontend implementation and frontend tests.
+- Mixed backend/frontend work should be split before execution.
+
+## Installed Project Surface
+
+```text
+.mcp.json
+model-routing.yaml
+.claude/settings.json
+.claude/hooks/route-edit.ps1
+.claude/commands/cgc*.md
+codecgc/features/
+codecgc/issues/
+codecgc/execution/
+codecgc/requirements/
+codecgc/architecture/
+codecgc/roadmap/
+codecgc/compound/
+codecgc/docs/
+codecgc/reference/
+```
+
+## Normal Loop
+
+1. Start with `/cgc <your request>` or `cgc "<your request>"`.
+2. Let CodeCGC decide whether the next step is planning, execution, review, or closure.
+3. Review execution audits with `/cgc-review` or `cgc-review`.
+4. Use `/cgc-history` or `cgc-history` when you need to find open work.
+
+## Recovery
+
+- If project integration looks wrong, run `cgc-install`, then `cgc-status`.
+- If runtime or executor startup fails, run `cgc-doctor`.
+- If a write is blocked, inspect `model-routing.yaml`; it is the project-local policy source of truth.
+- If an execution was rejected, use `/cgc` or `cgc` to continue the same workflow rather than starting a new one.
+
+## Stable References
+
+- `codecgc/reference/quickstart.md`
+- `codecgc/reference/onboarding.md`
+- `codecgc/reference/operation-guide.md`
+- `codecgc/reference/troubleshooting.md`
+- `codecgc/reference/path-contract.md`
+"""
+
+
+def write_project_onboarding_file(workspace_root: Path) -> Path:
+    path = workspace_root / PROJECT_ONBOARDING_RELATIVE_PATH
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(build_project_onboarding_text(), encoding="utf-8")
+    return path
+
+
+def onboarding_file_is_valid(path: Path) -> bool:
+    text = load_text_file(path)
+    if not text:
+        return False
+    required_markers = [
+        PROJECT_ONBOARDING_MARKER,
+        "/cgc-start",
+        "cgc-start",
+        "/cgc-status",
+        "cgc-status",
+        "model-routing.yaml",
+    ]
+    return all(marker in text for marker in required_markers)
+
+
 def build_hook_payload(command_text: str) -> dict[str, Any]:
     return {
         "PreToolUse": [
             {
-                "matcher": "Edit|Write",
+                "matcher": EDIT_GUARDRAIL_MATCHER,
                 "hooks": [
                     {
                         "type": "command",
@@ -117,6 +250,14 @@ def build_hook_payload(command_text: str) -> dict[str, Any]:
     }
 
 
+def policy_file_is_valid(path: Path) -> bool:
+    try:
+        load_policy(path)
+    except Exception:
+        return False
+    return True
+
+
 def _normalize_command_path_for_markdown(path: Path) -> str:
     return str(path).replace("\\", "\\\\")
 
@@ -323,6 +464,17 @@ def build_custom_command_templates(bin_dir: Path) -> dict[str, str]:
                 ],
                 fallback_command="cgc-external-audit",
             ),
+            build_mcp_first_command_template(
+                filename="cgc-external-status.md",
+                description="查看外部 MCP 能力状态面板",
+                argument_hint="[参数]",
+                primary_tool="codecgc.external_status",
+                direct_rules=[
+                    "映射可选字段 `workspace` 和 `format`。",
+                    "该命令用于日常快速查看外部能力登记状态与本地 MCP 观测结果。",
+                ],
+                fallback_command="cgc-external-status",
+            ),
             build_mcp_first_command_template(
                 filename="cgc-release-readiness.md",
                 description="运行 CodeCGC 发布就绪检查",
@@ -347,6 +499,57 @@ def build_custom_command_templates(bin_dir: Path) -> dict[str, str]:
             ),
         ]
     )
+    templates["cgc-install.md"] = """---
+description: Install or repair CodeCGC project-local integration
+argument-hint: "[optional install arguments]"
+---
+
+Use the `codecgc.install` MCP tool as the primary path.
+
+Default behavior:
+
+- Run project-local install for the current workspace.
+- Do not install user-level Claude files unless the user explicitly asks for `--mode user`.
+- Treat `model-routing.yaml` as the single routing policy source.
+
+Argument mapping:
+
+- No arguments: call `codecgc.install` with `mode: "local"`.
+- `status`: call `codecgc.install` with `mode: "status"`.
+- `doctor`: call `codecgc.install` with `mode: "doctor"`.
+- `--workspace <dir>`: pass the workspace through.
+- `--mode user-dry-run`: preview user-level files only.
+- `--mode user`: only run if the user explicitly asks to write user-level Claude integration.
+
+Fallback:
+
+- If the MCP tool is unavailable, run `cgc-install` with the same arguments from the target project root.
+- After install, run or suggest `cgc-start`, `cgc-status`, and `cgc-doctor`.
+"""
+    templates["cgc-start.md"] = """---
+description: Show the CodeCGC first-run entry guide for this project
+argument-hint: "[optional workspace]"
+---
+
+Use `codecgc.start` as the primary path.
+
+Default behavior:
+
+- Treat this as a read-only onboarding/status entry.
+- Summarize the project-local `codecgc/START_HERE.md` guide if present.
+- If the guide is missing, tell the user to run `/cgc-install`.
+- Keep the answer short and in Chinese.
+
+Argument mapping:
+
+- No arguments: call `codecgc.start`.
+- `--workspace <dir>`: pass the workspace through.
+
+Fallback:
+
+- If the MCP tool is unavailable, run `cgc-start` from the target project root.
+- If `cgc-start` reports missing onboarding, suggest `cgc-install`.
+"""
     return templates
 
 
@@ -361,6 +564,15 @@ def write_custom_command_files(target_dir: Path, bin_dir: Path) -> list[str]:
     return written
 
 
+def is_codecgc_route_edit_hook(hook: Any) -> bool:
+    if not isinstance(hook, dict):
+        return False
+    if hook.get("type") != "command":
+        return False
+    command = str(hook.get("command", "")).replace("\\", "/").lower()
+    return "route-edit.ps1" in command
+
+
 def merge_hook_settings(current: dict[str, Any], command_text: str) -> tuple[dict[str, Any], bool]:
     hooks = current.get("hooks")
     expected_hooks = build_hook_payload(command_text)
@@ -373,6 +585,23 @@ def merge_hook_settings(current: dict[str, Any], command_text: str) -> tuple[dic
         hooks["PreToolUse"] = expected_hooks["PreToolUse"]
         return current, True
 
+    changed = False
+    for item in list(pre_tool_use):
+        if not isinstance(item, dict):
+            continue
+        if item.get("matcher") not in LEGACY_EDIT_GUARDRAIL_MATCHERS | {EDIT_GUARDRAIL_MATCHER}:
+            continue
+        hook_list = item.get("hooks")
+        if not isinstance(hook_list, list):
+            continue
+        filtered_hooks = [hook for hook in hook_list if not is_codecgc_route_edit_hook(hook)]
+        if len(filtered_hooks) != len(hook_list):
+            changed = True
+            if filtered_hooks:
+                item["hooks"] = filtered_hooks
+            else:
+                pre_tool_use.remove(item)
+
     expected = expected_hooks["PreToolUse"][0]
     for item in pre_tool_use:
         if not isinstance(item, dict):
@@ -387,7 +616,7 @@ def merge_hook_settings(current: dict[str, Any], command_text: str) -> tuple[dic
             if not isinstance(hook, dict):
                 continue
             if hook.get("type") == "command" and hook.get("command") == expected["hooks"][0]["command"]:
-                return current, False
+                return current, changed
         hook_list.append(expected["hooks"][0])
         return current, True
 
@@ -466,7 +695,7 @@ def settings_have_hook_command(settings: dict[str, Any], command_text: str) -> b
     for item in pre_tool_use:
         if not isinstance(item, dict):
             continue
-        if item.get("matcher") != "Edit|Write":
+        if item.get("matcher") != EDIT_GUARDRAIL_MATCHER:
             continue
         hook_list = item.get("hooks")
         if not isinstance(hook_list, list):
@@ -490,8 +719,110 @@ def settings_have_allowed_tools(settings: dict[str, Any], allow_rules: list[str]
     return all(str(rule).strip() in existing for rule in allow_rules)
 
 
+RUNTIME_MCP_SERVER_SPECS: dict[str, dict[str, Any]] = {
+    "codecgc": {
+        "module": "codecgcmcp.cli",
+        "pythonpath_suffixes": ["scripts", "codecgcmcp/src"],
+    },
+    "codex": {
+        "module": "codexmcp.cli",
+        "pythonpath_suffixes": ["scripts", "codecgcmcp/src", "codexmcp/src"],
+    },
+    "gemini": {
+        "module": "geminimcp.cli",
+        "pythonpath_suffixes": ["scripts", "codecgcmcp/src", "geminimcp/src"],
+    },
+}
+
+
+def _normalize_path_parts(path_text: str) -> tuple[str, ...]:
+    text = str(path_text).replace("\\", "/").strip().rstrip("/")
+    if not text:
+        return ()
+    return tuple(part.lower() for part in text.split("/") if part)
+
+
+def _match_runtime_root(path_text: str, suffix: str) -> tuple[str, ...] | None:
+    parts = _normalize_path_parts(path_text)
+    suffix_parts = _normalize_path_parts(suffix)
+    if not parts or not suffix_parts or len(parts) < len(suffix_parts):
+        return None
+    if parts[-len(suffix_parts) :] != suffix_parts:
+        return None
+    return parts[: -len(suffix_parts)]
+
+
+def _collect_runtime_roots(entries: list[str], suffix: str) -> set[tuple[str, ...]]:
+    roots: set[tuple[str, ...]] = set()
+    for entry in entries:
+        root = _match_runtime_root(entry, suffix)
+        if root is not None:
+            roots.add(root)
+    return roots
+
+
+def mcp_server_matches_runtime_shape(server_payload: dict[str, Any], spec: dict[str, Any]) -> bool:
+    command_text = str(server_payload.get("command", "")).strip()
+    if not command_text:
+        return False
+
+    args = server_payload.get("args")
+    if args != ["-m", spec["module"]]:
+        return False
+
+    env = server_payload.get("env")
+    if not isinstance(env, dict):
+        return False
+
+    workspace_text = str(env.get("CODECGC_WORKSPACE_ROOT", "")).strip()
+    if not workspace_text:
+        return False
+
+    pythonpath_text = str(env.get("PYTHONPATH", "")).strip()
+    if not pythonpath_text:
+        return False
+
+    entries = [item.strip() for item in pythonpath_text.split(os.pathsep) if item.strip()]
+    if not entries:
+        return False
+
+    candidate_roots: set[tuple[str, ...]] | None = None
+    for suffix in spec["pythonpath_suffixes"]:
+        matching_roots = _collect_runtime_roots(entries, str(suffix))
+        if not matching_roots:
+            return False
+        candidate_roots = matching_roots if candidate_roots is None else candidate_roots & matching_roots
+        if not candidate_roots:
+            return False
+    return True
+
+
+def mcp_config_matches_runtime_shape(payload: dict[str, Any]) -> bool:
+    servers = payload.get("mcpServers")
+    if not isinstance(servers, dict):
+        return False
+
+    for server_name, spec in RUNTIME_MCP_SERVER_SPECS.items():
+        server_payload = servers.get(server_name)
+        if not isinstance(server_payload, dict):
+            return False
+        if not mcp_server_matches_runtime_shape(server_payload, spec):
+            return False
+    return True
+
+
 def build_workspace_hook_command(workspace_paths: dict[str, Path]) -> str:
-    return "powershell -ExecutionPolicy Bypass -File .claude/hooks/route-edit.ps1"
+    package_root = str(WORKSPACE).replace("'", "''")
+    workspace_root_path = Path(workspace_paths["root"])
+    hook_script_path = workspace_paths.get("hook_script", workspace_root_path / ".claude" / "hooks" / "route-edit.ps1")
+    workspace_root = str(workspace_root_path).replace("'", "''")
+    hook_script = str(hook_script_path).replace("\\", "/").replace("'", "''")
+    return (
+        "powershell -ExecutionPolicy Bypass -Command "
+        f"\"$env:CODECGC_PACKAGE_ROOT='{package_root}'; "
+        f"$env:CODECGC_WORKSPACE_ROOT='{workspace_root}'; "
+        f"& '{hook_script}'\""
+    )
 
 
 def build_mode_summary_payload(
@@ -513,11 +844,12 @@ def build_mode_summary_payload(
 
 def install_local_runtime(override_workspace: str = "") -> dict[str, Any]:
     workspace_paths = get_workspace_paths(override_workspace)
-    mcp_path = write_mcp_config(workspace_paths["mcp"])
+    mcp_path = write_mcp_config(workspace_paths["mcp"], workspace_paths["root"])
     routing_path = sync_workspace_routing_file(workspace_paths["routing_file"])
 
     workspace_paths["claude_dir"].mkdir(parents=True, exist_ok=True)
     workspace_paths["hooks_dir"].mkdir(parents=True, exist_ok=True)
+    workflow_dirs = ensure_workspace_workflow_dirs(workspace_paths["root"])
 
     settings = load_json_file(workspace_paths["settings"])
     merged_settings, settings_changed = merge_hook_settings(
@@ -533,11 +865,12 @@ def install_local_runtime(override_workspace: str = "") -> dict[str, Any]:
     if PROJECT_HOOK_PATH.resolve() != workspace_paths["hook_script"].resolve():
         shutil.copyfile(PROJECT_HOOK_PATH, workspace_paths["hook_script"])
     written_commands = write_custom_command_files(workspace_paths["commands_dir"], WORKSPACE / "bin")
+    onboarding_file = write_project_onboarding_file(workspace_paths["root"])
 
     summary = build_mode_summary_payload(
         scope="项目级 Claude 与 MCP 集成面",
         human_summary="项目级 CodeCGC 集成文件已同步。",
-        recommended_next_action="cgc-status",
+        recommended_next_action="cgc-start",
     )
 
     return {
@@ -549,13 +882,17 @@ def install_local_runtime(override_workspace: str = "") -> dict[str, Any]:
         "claude_settings": str(workspace_paths["settings"]),
         "hook_script": str(workspace_paths["hook_script"]),
         "commands_dir": str(workspace_paths["commands_dir"]),
+        "onboarding_file": str(onboarding_file),
+        "workflow_dirs": workflow_dirs,
         "command_files": written_commands,
         "notes": [
             "Repository-local MCP config was synced from the executor registry.",
-            "Project-local model-routing.yaml was synchronized and preserves custom path blocks.",
+            "Project-local model-routing.yaml was synchronized as the policy source of truth.",
+            "Project-local codecgc workflow directories were initialized.",
             "Claude pre-edit guardrail hook was synchronized into the target workspace.",
             "Claude MCP tool permissions were merged into project .claude/settings.json.",
             "Project-local Claude slash commands were synchronized into .claude/commands.",
+            "Project-local codecgc/START_HERE.md was written as the first-run entry guide.",
             "This mode prepares project-level integration surfaces for the selected workspace.",
         ],
         "summary": summary,
@@ -563,7 +900,15 @@ def install_local_runtime(override_workspace: str = "") -> dict[str, Any]:
 
 
 def build_user_hook_command(user_paths: dict[str, Path]) -> str:
-    return f"powershell -ExecutionPolicy Bypass -File {user_paths['hook_script']}"
+    package_root = str(WORKSPACE).replace("'", "''")
+    workspace_root = str(WORKSPACE).replace("'", "''")
+    hook_script = str(user_paths["hook_script"]).replace("'", "''")
+    return (
+        "powershell -ExecutionPolicy Bypass -Command "
+        f"\"$env:CODECGC_PACKAGE_ROOT='{package_root}'; "
+        f"$env:CODECGC_WORKSPACE_ROOT='{workspace_root}'; "
+        f"& '{hook_script}'\""
+    )
 
 
 def preview_user_install(override_root: str = "") -> dict[str, Any]:
@@ -571,8 +916,8 @@ def preview_user_install(override_root: str = "") -> dict[str, Any]:
     user_settings = load_json_file(user_paths["settings"])
     merged_settings, settings_changed = merge_hook_settings(user_settings, build_user_hook_command(user_paths))
     merged_settings, permissions_changed = merge_permission_settings(merged_settings, DEFAULT_ALLOWED_TOOLS)
-    mcp_config = build_mcp_config()
-    recommended_next_action = f"cgc-install --mode user --user-root {shell_quote(str(user_paths['root']))}"
+    mcp_config = build_mcp_config(WORKSPACE)
+    recommended_next_action = "cgc-install"
     summary = build_mode_summary_payload(
         scope="用户级 Claude 集成预演",
         human_summary="已完成用户级 Claude 集成预演，未写入任何文件。",
@@ -602,7 +947,7 @@ def preview_user_install(override_root: str = "") -> dict[str, Any]:
         },
         "notes": [
             "This mode does not modify user-level Claude files.",
-            "Use this preview to inspect the future user-level integration surface.",
+            "Use this preview only when intentionally inspecting a user-level integration surface.",
             "The preview includes MCP tool allow rules for codecgc, codex, and gemini servers.",
             "Current CodeCGC product policy still defaults to project-local installation.",
         ],
@@ -620,7 +965,7 @@ def install_user_runtime(override_root: str = "") -> dict[str, Any]:
     merged_settings, settings_changed = merge_hook_settings(settings, build_user_hook_command(user_paths))
     merged_settings, permissions_changed = merge_permission_settings(merged_settings, DEFAULT_ALLOWED_TOOLS)
     write_json_file(user_paths["settings"], merged_settings)
-    write_json_file(user_paths["mcp"], build_mcp_config())
+    write_json_file(user_paths["mcp"], build_mcp_config(WORKSPACE))
     shutil.copyfile(PROJECT_HOOK_PATH, user_paths["hook_script"])
     written_commands = write_custom_command_files(user_paths["commands_dir"], WORKSPACE / "bin")
     summary = build_mode_summary_payload(
@@ -683,9 +1028,11 @@ def build_install_mode_summary(result: dict[str, Any]) -> str:
             f"- Claude 设置: {result.get('claude_settings', '')}",
             f"- Hook 脚本: {result.get('hook_script', '')}",
             f"- Slash Commands: {result.get('commands_dir', '')}",
+            f"- 新手入口: {result.get('onboarding_file', '')}",
             "- 说明: 可选外部能力如 MemOS 不由 cgc-install 自动写入；如需启用，请在 Claude 中单独配置官方 MCP。",
         ]
         next_actions = [
+            "cgc-start",
             "cgc-status",
             "cgc-doctor",
         ]
@@ -707,7 +1054,7 @@ def build_install_mode_summary(result: dict[str, Any]) -> str:
         next_actions = []
         user_root = str(result.get("user_claude_root", "")).strip()
         if user_root:
-            next_actions.append(f"cgc-install --mode user --user-root {shell_quote(user_root)}")
+            next_actions.append("cgc-install")
         next_actions.append("cgc-install --mode status")
         return render_summary_block("CodeCGC 用户级预演", lines, next_actions)
 
@@ -734,13 +1081,16 @@ def build_install_mode_summary(result: dict[str, Any]) -> str:
 
 
 def collect_project_status(workspace_paths: dict[str, Path]) -> dict[str, Any]:
-    expected_mcp = build_mcp_config()
+    expected_mcp = build_mcp_config(workspace_paths["root"])
     expected_hook_command = build_workspace_hook_command(workspace_paths)
     expected_hook_text = load_text_file(PROJECT_HOOK_PATH)
     current_settings = load_json_file(workspace_paths["settings"])
     current_mcp = load_json_file(workspace_paths["mcp"])
     current_hook_text = load_text_file(workspace_paths["hook_script"])
     routing_exists = workspace_paths["routing_file"].exists()
+    policy_valid = policy_file_is_valid(workspace_paths["routing_file"]) if routing_exists else False
+    workflow_dirs_ready = workspace_workflow_dirs_ready(workspace_paths["root"])
+    onboarding_ready = onboarding_file_is_valid(workspace_paths["onboarding_file"])
 
     hook_registered = settings_have_hook_command(current_settings, expected_hook_command)
     permissions_registered = settings_have_allowed_tools(current_settings, DEFAULT_ALLOWED_TOOLS)
@@ -750,6 +1100,10 @@ def collect_project_status(workspace_paths: dict[str, Path]) -> dict[str, Any]:
     missing = []
     if not routing_exists:
         missing.append("routing_file")
+    if routing_exists and not policy_valid:
+        missing.append("routing_policy")
+    if not workflow_dirs_ready:
+        missing.append("workflow_dirs")
     if not mcp_matches:
         missing.append("mcp_json")
     if not hook_registered:
@@ -758,6 +1112,8 @@ def collect_project_status(workspace_paths: dict[str, Path]) -> dict[str, Any]:
         missing.append("claude_settings_permissions")
     if not hook_file_matches:
         missing.append("hook_script")
+    if not onboarding_ready:
+        missing.append("onboarding_file")
 
     ready = not missing
     return {
@@ -765,10 +1121,16 @@ def collect_project_status(workspace_paths: dict[str, Path]) -> dict[str, Any]:
         "routing_file_path": str(workspace_paths["routing_file"]),
         "claude_settings_path": str(workspace_paths["settings"]),
         "hook_script_path": str(workspace_paths["hook_script"]),
+        "onboarding_file_path": str(workspace_paths["onboarding_file"]),
         "mcp_json_exists": workspace_paths["mcp"].exists(),
         "routing_file_exists": routing_exists,
+        "routing_policy_valid": policy_valid,
+        "workflow_dirs_ready": workflow_dirs_ready,
+        "onboarding_ready": onboarding_ready,
+        "workflow_dirs_expected": [str(workspace_paths["root"] / item) for item in PROJECT_WORKFLOW_DIRS],
         "claude_settings_exists": workspace_paths["settings"].exists(),
         "hook_exists": workspace_paths["hook_script"].exists(),
+        "onboarding_exists": workspace_paths["onboarding_file"].exists(),
         "mcp_matches_expected": mcp_matches,
         "hook_registered": hook_registered,
         "permissions_registered": permissions_registered,
@@ -782,7 +1144,7 @@ def collect_project_status(workspace_paths: dict[str, Path]) -> dict[str, Any]:
 
 
 def collect_user_status(user_paths: dict[str, Path]) -> dict[str, Any]:
-    expected_mcp = build_mcp_config()
+    expected_mcp = build_mcp_config(WORKSPACE)
     expected_hook_command = build_user_hook_command(user_paths)
     expected_hook_text = load_text_file(PROJECT_HOOK_PATH)
     current_settings = load_json_file(user_paths["settings"])
@@ -791,7 +1153,9 @@ def collect_user_status(user_paths: dict[str, Path]) -> dict[str, Any]:
 
     hook_registered = settings_have_hook_command(current_settings, expected_hook_command)
     permissions_registered = settings_have_allowed_tools(current_settings, DEFAULT_ALLOWED_TOOLS)
-    mcp_matches = current_mcp == expected_mcp if user_paths["mcp"].exists() else False
+    mcp_matches_exact = current_mcp == expected_mcp if user_paths["mcp"].exists() else False
+    mcp_matches_runtime = mcp_config_matches_runtime_shape(current_mcp) if user_paths["mcp"].exists() else False
+    mcp_matches = mcp_matches_exact or mcp_matches_runtime
     hook_file_matches = current_hook_text == expected_hook_text if user_paths["hook_script"].exists() else False
 
     missing = []
@@ -814,6 +1178,8 @@ def collect_user_status(user_paths: dict[str, Path]) -> dict[str, Any]:
         "mcp_exists": user_paths["mcp"].exists(),
         "hook_exists": user_paths["hook_script"].exists(),
         "mcp_matches_expected": mcp_matches,
+        "mcp_matches_expected_exact": mcp_matches_exact,
+        "mcp_matches_runtime_shape": mcp_matches_runtime,
         "hook_registered": hook_registered,
         "permissions_registered": permissions_registered,
         "hook_file_matches_expected": hook_file_matches,
@@ -845,6 +1211,20 @@ def collect_install_status(override_workspace: str = "") -> dict[str, Any]:
         "scope": "项目级集成就绪状态，以及用户级 Claude 集成预演状态",
     }
 
+    status_summary.update(
+        {
+            "default_policy": "project-local-first",
+            "recommended_next_command": project_status["recommended_command"],
+            "recommended_user_command": "",
+            "human_summary": (
+                "Project-local CodeCGC integration is ready."
+                if project_status["ready"]
+                else "Project-local CodeCGC integration is missing or outdated."
+            ),
+            "scope": "project-local integration status; user-level config is optional preview only",
+        }
+    )
+
     return {
         "success": True,
         "mode": "status",
@@ -856,6 +1236,51 @@ def collect_install_status(override_workspace: str = "") -> dict[str, Any]:
     }
 
 
+def collect_start_status(override_workspace: str = "") -> dict[str, Any]:
+    workspace_paths = get_workspace_paths(override_workspace)
+    project_status = collect_project_status(workspace_paths)
+    onboarding_path = workspace_paths["onboarding_file"]
+    onboarding_ready = onboarding_file_is_valid(onboarding_path)
+    guide_text = load_text_file(onboarding_path) if onboarding_ready else ""
+    recommended_next_action = "cgc-status" if onboarding_ready else build_workspace_install_command(workspace_paths["root"])
+    human_summary = (
+        "CodeCGC first-run guide is ready. Start with /cgc or cgc after status/doctor are green."
+        if onboarding_ready
+        else "CodeCGC first-run guide is missing or outdated. Run project-local install first."
+    )
+    quick_actions = [
+        "/cgc-status",
+        "/cgc-doctor",
+        "/cgc <你的需求>",
+        "cgc-status",
+        "cgc-doctor",
+        "cgc \"你的需求\"",
+    ]
+    if not onboarding_ready:
+        quick_actions = ["/cgc-install", build_workspace_install_command(workspace_paths["root"])]
+
+    return {
+        "success": True,
+        "mode": "start",
+        "workspace": str(workspace_paths["root"]),
+        "summary": {
+            "ready": onboarding_ready,
+            "human_summary": human_summary,
+            "scope": "project-local first-run guide and next actions",
+            "recommended_next_action": recommended_next_action,
+            "quick_actions": quick_actions,
+        },
+        "onboarding": {
+            "path": str(onboarding_path),
+            "exists": onboarding_path.exists(),
+            "ready": onboarding_ready,
+            "relative_path": PROJECT_ONBOARDING_RELATIVE_PATH,
+            "guide_excerpt": guide_text[:1200],
+        },
+        "project": project_status,
+    }
+
+
 def find_python_command() -> str:
     candidates = ["python", "py"] if os.name == "nt" else ["python3", "python"]
     for candidate in candidates:
@@ -1065,11 +1490,20 @@ def classify_doctor_failures(
             )
             continue
 
-        if name in {"routing_file_exists", "project_hook_source_exists"}:
+        if name == "onboarding_file_ready":
+            add_failure(
+                "onboarding-guide-missing",
+                "项目级新手入口文件缺失或已过期。",
+                "重新执行项目级安装以同步 `codecgc/START_HERE.md` 与 `/cgc-start` 入口。",
+                install_command,
+            )
+            continue
+
+        if name in {"routing_file_exists", "routing_policy_valid", "project_hook_source_exists"}:
             add_failure(
                 "packaged-runtime-missing-files",
-                "运行时所需的路由文件或 hook 源文件缺失。",
-                "检查当前安装包是否完整，必要时重新安装或重新打包后再试。",
+                "运行时所需的 policy、路由文件或 hook 源文件缺失/无效。",
+                "重新执行项目级安装以同步 model-routing.yaml、policy-backed hook 与 Claude settings。",
             )
             continue
 
@@ -1104,6 +1538,21 @@ def collect_doctor_status(override_workspace: str = "") -> dict[str, Any]:
             "ok": workspace_paths["routing_file"].exists(),
             "detail": str(workspace_paths["routing_file"]),
         },
+        {
+            "name": "routing_policy_valid",
+            "ok": policy_file_is_valid(workspace_paths["routing_file"]) if workspace_paths["routing_file"].exists() else False,
+            "detail": str(workspace_paths["routing_file"]),
+        },
+        {
+            "name": "workflow_dirs_ready",
+            "ok": workspace_workflow_dirs_ready(workspace_paths["root"]),
+            "detail": str(workspace_paths["root"] / "codecgc"),
+        },
+        {
+            "name": "onboarding_file_ready",
+            "ok": onboarding_file_is_valid(workspace_paths["onboarding_file"]),
+            "detail": str(workspace_paths["onboarding_file"]),
+        },
         {
             "name": "project_hook_source_exists",
             "ok": PROJECT_HOOK_PATH.exists(),
@@ -1204,7 +1653,7 @@ def collect_doctor_status(override_workspace: str = "") -> dict[str, Any]:
 
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description="Install or inspect CodeCGC integration surfaces.")
-    parser.add_argument("--mode", choices=["local", "user-dry-run", "user", "status", "doctor"], default="local")
+    parser.add_argument("--mode", choices=["local", "user-dry-run", "user", "status", "doctor", "start"], default="local")
     parser.add_argument(
         "--format",
         choices=["json", "summary"],
@@ -1234,9 +1683,28 @@ def main() -> int:
         result = collect_install_status(args.workspace)
     elif args.mode == "doctor":
         result = collect_doctor_status(args.workspace)
+    elif args.mode == "start":
+        result = collect_start_status(args.workspace)
     else:
         raise ValueError(f"Unsupported install mode: {args.mode}")
 
+    if args.mode == "start" and args.format == "summary":
+        summary = result.get("summary", {}) if isinstance(result.get("summary"), dict) else {}
+        onboarding = result.get("onboarding", {}) if isinstance(result.get("onboarding"), dict) else {}
+        quick_actions = summary.get("quick_actions", []) if isinstance(summary.get("quick_actions"), list) else []
+        lines = [
+            f"- 工作区: {result.get('workspace', '')}",
+            f"- 范围: {summary.get('scope', '')}",
+            f"- 新手入口就绪: {format_bool_zh(summary.get('ready'))}",
+            f"- 入口文件: {onboarding.get('path', '')}",
+            f"- 摘要: {summary.get('human_summary', '')}",
+            f"- 快速动作: {format_list_zh(quick_actions)}",
+        ]
+        next_action = str(summary.get("recommended_next_action", "")).strip()
+        next_actions = [next_action] if next_action else []
+        print(render_summary_block("CodeCGC Start", lines, next_actions))
+        return 0 if result.get("success") else 1
+
     if args.mode == "status" and args.format == "summary":
         summary = result.get("summary", {}) if isinstance(result.get("summary"), dict) else {}
         project = result.get("project", {}) if isinstance(result.get("project"), dict) else {}
@@ -1249,6 +1717,7 @@ def main() -> int:
             f"- 策略: {summary.get('default_policy', '')}",
             f"- 摘要: {summary.get('human_summary', '')}",
             f"- 项目级缺失项: {format_list_zh(project.get('missing_or_outdated', []))}",
+            f"- 新手入口: {project.get('onboarding_file_path', '')}",
             f"- 用户级缺失项: {format_list_zh(user.get('missing_or_outdated', []))}",
         ]
         recommended_project = str(summary.get("recommended_project_command", "")).strip()