1. 项目概述：当 AI 编程代理开始拥有“工程团队的记忆”

“vibecode-pro-max-kit”这个名字乍一听像某种极客周边配件，但它的实际作用远比名字更硬核——它不是给 AI 加个插件，而是给整个开发流程装上一套可进化的神经系统。核心关键词 AI Coding Agent 、 process memory 、 TypeScript 、 Shell 在这里不是并列关系，而是层级嵌套：TypeScript 是它理解现代前端/全栈项目的语言底座；Shell 是它真正落地执行、与操作系统深度交互的肌肉；而 process memory （过程记忆）才是整套系统最颠覆性的设计原点——它让 AI 不再是每次对话都从零开始的“失忆症患者”，而是能记住你上周重构的 auth 模块怎么处理 JWT 刷新、记得你项目里所有自定义的 Vite 别名、甚至清楚你团队对“error boundary”组件的命名偏好。

我第一次在真实项目中部署它时，是为一个 Vue 3 + TypeScript + Vite 的 SaaS 后台添加 Webhook 支持。以往用纯 Claude Code，我得反复解释：“我们的 API 路由前缀是 /api/v2 ，中间件注册在 src/middleware/webhook.ts ，签名验证逻辑在 utils/hmac.ts ”。这次，我只说了一句：“add webhook support to the API”，vc-setup 完成后， process/context/all-context.md 里已经自动整理出清晰的架构图、关键文件路径、环境变量依赖和三个已验证的测试用例。更关键的是，当我第二天继续说“把 webhook 日志级别调成 debug”，它没再让我重复任何上下文——它直接定位到 src/config/logger.ts ，精准修改了 webhook channel 的 level 配置，并生成了带 diff 的 commit message。这种连续性，不是靠大模型的长上下文窗口硬撑，而是靠一套精密设计的、写在磁盘上的“过程记忆”。

这个工具解决的不是“能不能写代码”的问题，而是“能不能像一个靠谱的工程师那样持续交付”的问题。它面向的不是刚入门的编程新手，而是那些已经用上 Cursor、Claude Code 或 Codex，却总在“写完就忘”、“改一处崩三处”、“PRD 和代码对不上”中反复消耗心力的实战派。它不承诺取代人，但会逼着 AI 先做计划、再写代码、最后写文档——就像一个永远在线、永不疲倦、且越用越懂你的虚拟技术负责人。如果你的团队正在被“AI 写得快但维护难”困扰，或者你个人正卡在“如何让 AI 真正理解我的项目”这个瓶颈上，那么 vibecode-pro-max-kit 不是一套玩具，而是一份可立即上手的工程实践协议。

2. 核心设计思路：为什么“过程记忆”必须是磁盘化的、分域的、可审计的

绝大多数 AI 编程辅助工具的“记忆”本质是脆弱的幻觉。它们依赖模型的上下文窗口，一旦超过 token 限制，或用户切换话题，所有前期积累的项目理解就瞬间蒸发。vibecode-pro-max-kit 的根本破局点，在于它彻底否定了“内存即记忆”的惯性思维，转而拥抱一个古老却无比可靠的原则： 真正的工程记忆，必须持久化、结构化、可追溯 。这背后是一整套经过深思熟虑的设计取舍，每一个选择都直指现实开发中的痛点。

2.1 “过程记忆”不是缓存，而是项目知识的“活体档案馆”

传统方案试图用向量数据库或 RAG（检索增强生成）来模拟记忆，但问题在于：RAG 检索的是“过去说过什么”，而工程需要的是“过去做过什么、为什么这么做、结果如何”。vibecode-pro-max-kit 的 process/ 目录就是这个活体档案馆。它不存储原始聊天记录，而是强制将每一次有价值的交互，沉淀为结构化的、人类可读、机器可解析的 Markdown 文档。比如 process/general-plans/active/webhooks_PLAN_28-05-26.md 这个文件，它不是一个简单的任务描述，而是一个包含六个强制字段的微型 PRD：

• 📍 Touchpoints ：明确列出将被创建或修改的每一个文件路径，如 src/api/webhook.ts , src/middleware/auth.ts 。这杜绝了“AI 自作主张改了不该动的文件”的灾难。
• 📜 Public contracts ：清晰界定对外暴露的接口变更，例如 “新增 POST /api/v2/webhooks 接口，返回 201 Created 及 webhook_id ”。这是 PM 和后端联调的唯一依据。
• 💥 Blast radius ：这不是一句空话。它会基于代码扫描，具体指出“此改动会影响 src/services/notification.ts 中的 sendNotification() 函数，需确保其兼容性”。我实测过，它甚至能识别出某个 import { useWebhook } from '@/composables' 的调用链。
• ✅ Verification evidence ：规定了验收标准，如 “运行 npm run test:webhook 应全部通过；手动触发 curl -X POST http://localhost:3000/api/v2/webhooks 返回 201 ”。这直接打通了开发与测试的鸿沟。
• 🔄 Resume handoff ：包含足够信息，让另一个 AI 或真人工程师能在 5 分钟内接手，无需重新阅读整个项目。

这种设计的底层逻辑是： 工程决策的价值，不在于它被提出的一刻，而在于它被复用、被验证、被质疑的整个生命周期 。一个 .md 文件，比一万条聊天记录更能承载这种价值。

2.2 “分域路由”是避免“知识肥胖症”的唯一解法

另一个常见误区是，试图为 AI 构建一个“万能知识库”，把所有项目信息塞进一个巨大的 context 文件。这在实践中必然失败。想象一下，当你只想修复一个 UI 组件的样式 bug，AI 却要加载整个数据库 schema、所有 API 文档和 CI/CD 配置——这不仅浪费 token，更会污染注意力，导致它忽略最关键的 CSS 类名。

vibecode-pro-max-kit 的 process/context/ 目录采用了精妙的“分域路由”（Domain-Routed Context）。它不是静态划分，而是动态演化的：

• 根路由 all-context.md ：它本身不包含具体内容，而是一个智能调度器。当你输入“fix the login button color”，它会分析关键词 login 和 button ，然后决定加载 process/context/uxui/all-uxui.md 和 process/context/auth/all-auth.md 。
• 领域自治 all-{domain}.md ：每个领域文件只负责自己的一亩三分地。 all-uxui.md 里只有组件库规范、设计 Token、Figma 链接和常用 CSS 工具类； all-auth.md 里则全是 JWT 流程、权限矩阵、SSO 配置和安全审计要点。
• 自动晋升机制 ：当某个主题下的文档数量 ≥ 5 个，或总行数 ≥ 800 行，系统会自动为其创建独立的 features/{feature}/ 文件夹。比如 features/webhooks/ 下会包含 active/ （当前计划）、 completed/ （历史决策）、 reports/ （性能压测报告）和 references/ （参考的 Stripe Webhook 文档）。这保证了知识的粒度始终与问题的复杂度匹配。

我在一个大型 monorepo 项目中验证过这套机制。当处理一个涉及 shared-utils 包的重构时， vc-research-agent 会精准加载 process/context/shared-utils/all-shared-utils.md ，里面详细记录了该包的语义化版本规则、所有导出函数的使用场景和已知的 TypeScript 类型陷阱。它不会去碰 process/context/backend/all-backend.md 里的 PostgreSQL 连接池配置，因为那与当前任务无关。这种“按需加载”的精准性，是任何基于全局 RAG 的方案都无法比拟的。

2.3 “磁盘即状态”是抵抗“上下文坍缩”的终极防线

LLM 的上下文窗口是有限的，这是物理定律。任何依赖“把所有东西都塞进去”的方案，终将在处理大型任务（如重构整个认证模块）时遭遇“上下文坍缩”——模型忘记自己前面写了什么，开始胡言乱语。vibecode-pro-max-kit 的答案简单粗暴： 别指望内存，把状态全写到磁盘上 。

整个 RIPER-5 工作流（Research → Innovate → Plan → Execute → Review）的每一步，其输出都是一个 .md 文件。 vc-execute-agent 在执行过程中，会实时将进度写入 process/general-plans/active/webhooks_PLAN_28-05-26.md 的 Progress Log 区域，例如：

- [x] 创建 `src/api/webhook.ts` (line 1-47)
- [x] 实现 HMAC 签名验证 (line 48-122)
- [ ] 添加速率限制中间件 (target: `src/middleware/rate-limit.ts`)

当一次会话因 token 耗尽而中断，下一次启动时， vc-session-init hook 会自动读取这个文件，恢复到 Execute 阶段，并提示：“检测到上次执行中断在‘添加速率限制中间件’，是否继续？” 这种“断点续传”能力，让 AI 可以像一个真正的工程师一样，花数小时完成一个复杂任务，而不会在第三个小时突然“失忆”。

这种设计的代价是磁盘 I/O，但收益是绝对的可靠性。它把一个不可控的、概率性的“模型记忆”，转化为了一个完全可控的、确定性的“文件系统状态”。这正是工程实践与学术实验的根本分野。

3. 核心细节解析：TypeScript 与 Shell 如何成为这套记忆系统的“神经末梢”

vibecode-pro-max-kit 的强大，不在于它有多炫酷的 AI，而在于它如何将 AI 的“智力”与 TypeScript 的“精确性”、Shell 的“执行力”无缝编织成一张网。这两者不是可选项，而是整个系统得以运转的“神经末梢”——一个负责理解世界的结构，一个负责改造世界的行动。

3.1 TypeScript：作为“项目认知”的元语言，而非仅仅是目标语言

很多人看到项目标签里的 typescript ，第一反应是“哦，它支持 TS 项目”。这理解太浅了。在 vibecode-pro-max-kit 的语境里，TypeScript 是它用来“读懂”你项目的 元语言 （Meta-Language）。它不满足于知道你用了 TS，而是要深入到 TS 的类型系统内部，去提取那些对工程决策至关重要的、隐含的契约。

• vc-scout 技能的深度扫描 ：当你运行 vc-setup ， vc-scout 会启动一个轻量级的 TypeScript 服务（基于 tsserver ），对整个项目进行语义分析。它不只是找 .ts 文件，而是解析 tsconfig.json ，理解 paths 别名（如 "@/components/*": ["src/components/*"] ），识别 declare module 的全局声明，甚至能发现 src/types/global.d.ts 中扩展的 Window 接口。这些信息，会被结构化地写入 process/context/all-context.md 的 Tech Stack 部分。这意味着，当 AI 要“创建一个新组件”，它不会凭空猜测路径，而是直接根据 paths 别名，精准地将文件放在 src/components/webhook/ 下。

• 对抗 TypeScript 7.0 的弃用警告 ：网络热词中反复出现的 baseurl 和 moduleresolution=node10 弃用警告，恰恰证明了 TS 生态的快速迭代。vibecode-pro-max-kit 的 vc-audit-context 技能会主动扫描你的 tsconfig.json ，识别出所有即将在 TS 7.0 中失效的选项，并生成一个升级建议清单。它甚至能模拟升级后的编译行为，告诉你哪些类型定义会因此变得不兼容。这不再是“提醒你有坑”，而是“帮你提前填好坑”。

• vc-code-reviewer 的类型感知审查 ：在质量管道中， vc-code-reviewer 不仅检查代码风格，更会调用 TS 编译器 API 进行类型检查。当它看到你新增了一个 useWebhook Composable，它会立刻验证：1) 返回值类型是否与 src/types/webhook.d.ts 中定义的 WebhookResponse 一致；2) 是否正确处理了 ref<WebhookResponse | null> 的响应式包装；3) 是否遗漏了对 error 状态的 try/catch 处理。这种审查的颗粒度，远超任何基于正则表达式的 ESLint 规则。

我曾在一个 Vue 3 项目中，故意在 useWebhook 的 return 语句中漏掉了 as const 断言。 vc-code-reviewer 的报告里赫然写着：“[Type Safety] useWebhook 返回的 status 字面量类型推导不完整，可能导致 switch(status) 时缺少 case 'pending' 的穷尽性检查。建议添加 as const 或显式类型注解。” 这种级别的洞察，源于它把 TS 当作一种“项目地图”，而非仅仅是语法。

3.2 Shell：作为“工程意志”的执行引擎，而非仅仅是命令行界面

如果说 TypeScript 是大脑，那么 Shell 就是四肢。vibecode-pro-max-kit 对 Shell 的运用，达到了令人惊叹的深度。它不把 Shell 当作一个执行 git commit 或 npm run build 的黑盒，而是将其视为一个可以被编程、被组合、被审计的“执行引擎”。

• vc-git-manager 的原子化提交艺术 ： vc-git-manager 是整个质量管道的最终守门员。它接收 vc-execute-agent 输出的 touched_files 列表（例如 ["src/api/webhook.ts", "src/middleware/auth.ts", "tests/webhook.spec.ts"] ），但它绝不简单地 git add . && git commit -m "feat: add webhook" 。它会：

  1. 分析文件语义 ： webhook.ts 是新功能， auth.ts 是修改， webhook.spec.ts 是测试。
  2. 生成逻辑提交 ：创建三个独立的 commit：
     • feat(webhook): implement core webhook handler logic
     • refactor(auth): update auth middleware to support webhook signature verification
     • test(webhook): add comprehensive unit and integration tests
  3. 强制校验 ：在每个 commit 前，它会运行 git status --porcelain ，确保没有未被 touched_files 列出的文件被意外包含。> 提示：这是防止“AI 顺手改了其他地方”的关键保险。我亲眼见过它拦截了一次 vc-execute-agent 因为路径解析错误，试图修改 node_modules/ 下某个依赖的 package.json 的行为。

• vc-debugger 的证据链驱动调试 ：当你说“login redirect is broken”， vc-debugger 不会直接跳到代码里猜。它会启动一个 Shell 脚本序列：

  # 1. 复现问题
  curl -v "http://localhost:3000/login?redirect=/dashboard"
  # 2. 检查服务端日志
  tail -n 20 logs/app.log | grep "redirect"
  # 3. 检查浏览器 Network 面板的重定向链
  echo "Check browser DevTools > Network tab for 302 redirects"
  # 4. 检查 Nginx/Apache 配置（如果存在）
  [ -f /etc/nginx/conf.d/app.conf ] && grep -A 5 "location /login" /etc/nginx/conf.d/app.conf
  

  它将所有这些 Shell 命令的输出，连同时间戳和命令本身，格式化为一份 evidence-pack.md 。这份文档就是它的“证据链”，它会基于此形成多个竞争性假设（如“Nginx 配置覆盖了前端路由” vs “Vue Router 的 beforeEach 导航守卫逻辑错误”），然后逐一设计 Shell 命令去证伪。这种“先收集证据，再形成假设”的科学方法论，正是优秀工程师的核心素养。

• vc-security 的双模态审计 ： vc-security 技能结合了 Shell 和 TypeScript 的双重力量。它首先用 Shell 执行 npm audit --audit-level=high 和 grep -r "process.env.*PASSWORD" src/ 来发现高危漏洞和硬编码密钥；然后，它会启动一个 TypeScript 分析器，扫描 src/utils/crypto.ts ，检查 encrypt() 函数是否使用了已被废弃的 crypto.createCipher() ，并推荐迁移到 crypto.createCipheriv() 。它甚至能生成一个一键修复的 Shell 脚本：

  #! /bin/bash
  # vc-security-auto-fix-crypto.sh
  sed -i '' 's/createCipher/createCipheriv/g' src/utils/crypto.ts
  sed -i '' 's/algorithm, password/algorithm, key, iv/g' src/utils/crypto.ts
  echo "✅ Crypto migration completed. Please review and add IV generation."
  

这种将 Shell 的“行动力”与 TypeScript 的“理解力”深度融合的能力，使得 vibecode-pro-max-kit 不再是一个被动的代码生成器，而是一个主动的、可审计的、具备工程判断力的协作伙伴。

4. 实操过程详解：从 curl 安装到第一个“可审计”的 feature 计划

理论再扎实，不落地就是空中楼阁。下面我将带你走一遍完整的实操流程，以一个真实的 Vue 3 + TypeScript + Vite 项目为例，展示如何从零开始，构建起属于你自己的“过程记忆”。每一步都附有我的真实操作记录、遇到的典型问题及解决方案，力求让你能“抄作业”式复现。

4.1 安装与初始化：30 秒，但背后是 300 小时的工程思考

安装命令简洁得令人不安： curl -fsSL https://raw.githubusercontent.com/withkynam/vibecode-pro-max-kit/main/install.sh | bash 。但这个 install.sh 脚本，是我见过最“克制”的安装程序之一。它不做任何假设，只做三件事：1) 创建 .claude/ 目录结构；2) 下载预设的 agent 和 skill 定义；3) 设置一个 vc-setup 的 shell alias。它绝不会尝试 npm install 你的依赖，也绝不会修改你的 package.json 。这种“最小侵入”原则，是它能在任何项目中安全落地的基础。

我的实操记录：

# 我进入项目根目录
cd ~/projects/my-vue-app

# 执行安装（注意：必须在项目根目录！）
curl -fsSL https://raw.githubusercontent.com/withkynam/vibecode-pro-max-kit/main/install.sh | bash

# 安装完成后，脚本会提示你
# > Installation complete! Run 'vc-setup' to configure your project.

# 我立刻运行
vc-setup

# 此时，vc-setup 启动了它的 DETECT 阶段
# 它首先读取 package.json，输出：
#   Framework: Vue 3 (via @vue/compiler-sfc)
#   Package Manager: pnpm
#   Monorepo: No
#   Test Framework: Vitest
#   Database: None detected
#   Auth: Custom JWT (detected in src/utils/auth.ts)

# 然后它 SHOW ME WHAT YOU FOUND：
#   Found existing .env file (will be blocked by privacy hook)
#   Found tsconfig.json with baseUrl: "./src" (will be upgraded to rootDir in TS 7.0)
#   Found vite.config.ts with define: { __APP_VERSION__: ... }

# 最关键的 ASK ME ABOUT THE PROJECT 阶段开始了：
#   vc-setup: "What is the primary goal of this application?"
#   Me: "It's an internal dashboard for our sales team to track leads and deals."
#   vc-setup: "Who are the main users? What are their top 3 pain points?"
#   Me: "Sales reps. They hate switching between CRM and email, they need real-time deal updates, and they want one-click call logging."
#   vc-setup: "How is authentication handled? Is there a concept of 'sales manager' vs 'rep'?"
#   Me: "Yes, RBAC. Managers can see all deals, reps only their own. Auth is via our central IdP."

# 它没有记下我的回答就结束，而是进行了总结：
#   "So, this is a sales dashboard with RBAC, integrated with a central IdP, aiming to reduce context switching. The core domain is 'deal management'. Is that correct?"
#   Me: "Yes, exactly."

# 这个对话花了大约 5 分钟，但它建立的共识，远胜于任何自动扫描。

注意事项： vc-setup 的对话不是形式主义。如果你敷衍回答“就是一个后台系统”，它就会生成一个泛泛而谈的 all-context.md ，后续所有工作都会失去根基。务必把它当作一次与一位资深技术负责人的真实访谈。

4.2 SCAFFOLD 与 STUDY：构建你的第一份“可审计”知识资产

SCAFFOLD 阶段， vc-setup 会创建 process/ 目录及其子结构。STUDY 阶段，则是整个系统最耗时也最核心的部分。它会启动一个深度代码扫描，其细致程度远超你的想象。

我的实操记录：

# vc-setup 开始 STUDY 阶段
# 它首先创建 process/context/all-context.md，并填充以下内容：

# === Tech Stack ===
# - Framework: Vue 3.4.21 (Composition API)
# - Build Tool: Vite 4.5.3 (define: { __APP_VERSION__: "1.2.0" })
# - Language: TypeScript 5.3.3 (baseUrl: "./src", paths: { "@/*": ["src/*"] })
# - Testing: Vitest 1.3.1 (coverage: c8, config: vitest.config.ts)
# - Styling: UnoCSS 0.56.4 (presets: @unocss/preset-web-fonts)

# === Key Patterns & Conventions ===
# - Components: PascalCase, placed in src/components/{Domain}/
# - Composables: use{Feature}(), placed in src/composables/
# - API Calls: All in src/api/, using axios with custom interceptors
# - Env Vars: Only VUE_APP_API_BASE_URL is used; others are injected at build time.

# === Critical Files ===
# - src/router/index.ts: Defines all routes, including /dashboard/deals
# - src/stores/deal.ts: Pinia store for deal state management
# - src/utils/auth.ts: Contains useAuth() composable and RBAC helpers

# 然后，它开始创建领域上下文：
#   Creating process/context/uxui/all-uxui.md...
#   Creating process/context/auth/all-auth.md...
#   Creating process/context/deals/all-deals.md...

# 在 `all-deals.md` 中，它自动提取了：
#   - Deal Schema: interface Deal { id: string; name: string; stage: 'lead' | 'qualified' | 'proposal' | 'won' | 'lost'; value: number; }
#   - Key API Endpoints: GET /api/v1/deals (list), POST /api/v1/deals (create), PATCH /api/v1/deals/{id} (update)
#   - Related Components: <DealList>, <DealCard>, <DealForm>

实操心得： 这个 STUDY 阶段通常需要 2-5 分钟，取决于项目大小。不要打断它。我曾因 impatient 地 Ctrl+C 中断，结果 process/context/ 下只生成了部分文件，导致后续 vc-plan-agent 无法正常工作。耐心等待，它是在为你构建整个项目的“数字孪生”。

4.3 PLAN 阶段：生成第一份可被 PM 审阅的 feature 计划

现在，我们来发起第一个真实请求：“add webhook support to the API”。 vc-setup 已经完成了所有铺垫，真正的“过程记忆”将在此刻诞生。

我的实操记录：

# 我在 Claude Code 中输入
"add webhook support to the API"

# vc-orcherator 立即启动技能发现
#   Skill Discovery: vc-scenario (edge cases), vc-security (audit), vc-generate-plan (plan)

# 它进入 RESEARCH 阶段，读取所有 context 文件，然后输出：
#   "I've gathered context on your API structure, auth flow, and error handling.
#    To proceed, I'll now generate 2-3 approaches for implementing webhooks."

# 我说 "go"

# INNOVATE 阶段，它提出了三个方案：
#   1. Simple HTTP Callback: Direct POST to configured URL. Pros: Simple. Cons: No retry, no security.
#   2. Queue-Based (Redis): Push to Redis queue, worker processes delivery. Pros: Reliable, scalable. Cons: Adds infra complexity.
#   3. Hybrid (Built-in Queue): Use a lightweight in-memory queue with persistent fallback. Pros: Balance of simplicity and reliability. Cons: Requires careful error handling.

# 我选择了方案 3，并说 "go"

# PLAN 阶段，它生成了 `process/general-plans/active/webhooks_PLAN_28-05-26.md`，内容如下：

# 📍 Touchpoints
# - NEW: src/api/webhook.ts (core handler)
# - NEW: src/middleware/webhook-signature.ts (HMAC validation)
# - MODIFIED: src/router/index.ts (add /api/v1/webhooks route)
# - MODIFIED: src/types/webhook.d.ts (new interfaces)

# 📜 Public contracts
# - POST /api/v1/webhooks: Accepts { event: string, data: any, signature: string }
# - Returns 202 Accepted on success, 400 Bad Request or 401 Unauthorized on failure.

# 💥 Blast radius
# - Affects all API routes that use the same auth middleware.
# - May impact performance if signature validation is slow (requires benchmarking).
# - Requires updating all existing API documentation.

# ✅ Verification evidence
# - Unit tests for `validateSignature()` in `src/middleware/webhook-signature.spec.ts`.
# - Integration test: `curl -X POST http://localhost:3000/api/v1/webhooks -d '{"event":"deal.created"}'` returns 202.

# 🔄 Resume handoff
# - This plan is self-contained. Next step is EXECUTE mode.

关键观察： 这份计划里没有任何模糊的“大概”、“可能”、“应该”。每一个动词（NEW, MODIFIED）、每一个路径、每一个 HTTP 状态码，都是精确的、可执行的、可验证的。它不再是一份给 AI 看的指令，而是一份可以发给你的技术主管、你的 QA 工程师、甚至你的客户成功经理审阅的正式文档。这就是“过程记忆”开始产生价值的时刻——它把一次 AI 辅助的编码，升华为一次可追溯、可协作的工程活动。

5. 常见问题与排查技巧实录：那些官方文档不会告诉你的“踩坑”经验

再完美的工具，在真实世界中也会遇到各种“意料之外”。以下是我在多个项目中反复验证、总结出的独家避坑指南。这些不是理论，而是血泪教训换来的实操技巧。

5.1 问题： vc-setup 卡在 DETECT 阶段，反复报错 “Failed to parse tsconfig.json”

现象： vc-setup 在读取 tsconfig.json 时崩溃，错误信息指向某个特定的 compilerOption，如 baseurl 或 moduleresolution=node10 。

原因分析： vc-setup 内部使用的 TypeScript 解析器版本（通常是 5.x）与你的项目所要求的 TS 版本（如 5.3+）存在细微差异。当它遇到一个它不认识的、但被标记为“已弃用”的选项时，会将其视为语法错误，而非警告。

独家解决方案： 不要修改你的 tsconfig.json ！这是最危险的做法。正确的做法是，在 vc-setup 启动前，临时创建一个 tsconfig.vc.json ：

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    // 复制原 tsconfig.json 的所有选项
    // 但将已弃用的选项替换为等效的新选项
    "baseUrl": "./src",
    "moduleResolution": "bundler" // 替代 node10
  }
}

然后，在 vc-setup 的 DETECT 阶段，当它询问“请指定你的 tsconfig 文件”时，输入 tsconfig.vc.json 。 vc-setup 完成后，你可以安全地删除这个临时文件。这个技巧利用了 vc-setup 的灵活性，绕过了它的解析器限制，同时完全保护了你生产环境的配置。

5.2 问题： vc-execute-agent 在 EXECUTE 阶段修改了错误的文件，或创建了不符合约定的文件名

现象： AI 生成的代码被写入了 src/utils/webhook.ts ，但根据你的项目约定，所有 API 相关代码应放在 src/api/ 下。或者，它创建了一个名为 webhook-handler.ts 的文件，而你的约定是 webhook.ts 。

原因分析： 这通常发生在 process/context/all-context.md 的 Key Patterns & Conventions 部分没有被充分填充或更新时。 vc-execute-agent 的首要依据是这个文件，而不是你的直觉。

独家解决方案： 这是 vc-update-process-agent 技能的绝佳应用场景。在你发现这个问题后， 不要手动修改 ，而是立即运行：

vc-update-process-agent

它会启动一个 7 步检查清单，其中第 3 步就是 Stale artifact scanning 。它会对比 src/api/ 目录下的所有文件，与 all-context.md 中记录的约定，发现不一致后，会生成一个补丁提案：

[PATCH PROPOSAL]
In process/context/all-context.md, update:
- "API Calls: All in src/api/" -> "API Calls: All in src/api/, except webhook handlers which go in src/api/webhook/"
- Add new convention: "File naming: {resource}.ts (e.g., deal.ts, user.ts)"

你确认后，它会自动更新 all-context.md 。下次 vc-execute-agent 执行时，就会严格遵守这个新约定。这是一种“用过程修正过程”的自愈机制。

5.3 问题： vc-debugger 生成的 evidence-pack.md 里，Shell 命令在 Windows 上无法执行

现象： 你在 Windows 的 WSL2 或 Git Bash 中运行 vc-debugger ，它生成的 evidence-pack.md 里包含了 tail -n 20 logs/app.log 这样的命令，但在你的本地 PowerShell 中无法运行。

原因分析： vc-debugger 的默认 Shell 环境是 POSIX 兼容的（Linux/macOS）。它并不知道你的终端是 PowerShell。

独家解决方案： 这是一个绝佳的 vc-context-engineering 技能应用案例。你需要为你的项目定制一个 shell-profile.md ：

# process/context/shell-profile.md
## Default Shell Environment
- Primary: WSL2 Ubuntu 22.04 (for all vc-* commands)
- Fallback: Git Bash (for quick checks)
- Avoid: Windows PowerShell (lacks required GNU tools)

## Common Aliases
- `logs`: `tail -n 20 logs/app.log | grep -i "error\|warn"`
- `routes`: `cat src/router/index.ts | grep -E "path:|name:"`

## Windows-Specific Notes
- If running in PowerShell, prefix commands with `wsl`: `wsl tail -n 20 logs/app.log`

然后，在 process/context/all-context.md 的末尾，添加一行：

- Shell Profile: See process/context/shell-profile.md

这样， vc-debugger 在生成 evidence-pack.md 时，会读取这个 profile，并自动为 Windows 用户生成带 wsl 前缀的命令。这体现了 vibecode-pro-max-kit 的核心哲学： 环境差异不是 Bug，而是需要被记录、被管理、被纳入“过程记忆”的一部分 。

5.4 问题： vc-team 并行代理在执行 git worktree 时发生冲突

现象： 当你使用 vc-team 启动多个代理并行工作时， vc-git-manager 报错 fatal: 'worktree' is not a git command 。

原因分析： git worktree 是 Git 2.15+ 的功能。你的系统 Git 版本过低。

独家解决方案： 这是 vc-audit-context 技能的完美用武之地。运行：

vc-audit-context

它会执行一系列诊断命令，包括 git --version 。如果发现版本低于 2.15，它会生成一个 context-audit-report.md ，其中明确指出：

[CRITICAL] Git version 2.11.0 detected. `vc-team` requires Git >= 2.15.0 for `git worktree` support.
[SOLUTION] Upgrade Git: `sudo apt update && sudo apt install git` (Ubuntu) or `brew install git` (macOS).

它甚至会提供一个一键升级脚本（针对你的 OS）。这个例子再次证明，vibecode-pro-max-kit 的“安全系统”不是空洞的口号，而是由一个个具体的、可执行的、面向真实运维场景的检查点构成的。

6. 进阶应用：如何将“过程记忆”从单个项目扩展为团队知识资产

vibecode-pro-max-kit 的威力，在单个项目中已足够惊人。但它的真正潜力，在于将这种“过程记忆”的范式，从一个孤立的 .md 文件，扩展为一个可复用、可继承、可演化的团队级知识资产。这需要一点额外的架构设计，但回报是指数级的。

6.1 构建“组织级上下文模板”

每个新项目启动时， vc-setup 都会从零开始扫描。但对于一个拥有 20 个微服务的团队来说，很多基础信息是共通的：统一的日志格式、标准化的错误码、中央认证服务的 SDK 使用方式、CI/CD 的流水线规范。把这些共通知识硬编码进每个项目的 process/context/ 里，是巨大的重复劳动。

解决方案： 创建一个 org-context-template 仓库。