项目上下文与已有项目接管¶
1. 使用场景¶
以下情况建议先执行 Project Onboarding:
- 第一次进入陌生仓库;
- 同时维护多个相似项目;
- 项目跨会话或长期维护;
- 准备执行 Commit、Push、部署、重启或数据写入;
- 历史文档与实际代码可能不一致。
简单一次性只读问题可以不创建 Project Profile,但必须明确当前仓库和分支。
2. Onboarding 命令¶
python3 scripts/cp-runtime.py project-onboard \
--repo-path /path/to/repo \
--project-id logistics-system \
--project-name "AI 物流管理系统"
指定自定义仓库外目录:
python3 scripts/cp-runtime.py project-onboard \
--repo-path /path/to/repo \
--context-dir /secure/external/context/logistics-system
3. 自动识别范围¶
工具只读取:
- Git 根目录、Branch、HEAD、Remote 和工作区状态;
- 根目录构建标记;
- 根目录一级模块标记;
pom.xml、package.json等有限文件中的框架或脚本声明。
不会:
- 深度扫描全部源码;
- 执行构建、测试或启动;
- 访问网络、数据库或生产环境;
- 读取
.env并保存凭据; - 将启发式推断标为已确认。
4. 校对 Profile¶
首次生成后重点检查:
identity.repo_path和remote_origin;technology是否遗漏主要技术栈;entrypoints的confidence;boundaries中的环境、数据敏感等级、所有权;unknowns是否已经被实际证据解决;prohibited_paths是否覆盖依赖、构建产物和敏感目录。
5. 刷新与验证¶
python3 scripts/cp-runtime.py project-refresh \
--profile /path/to/project-profile.json
python3 scripts/cp-runtime.py project-validate \
--profile /path/to/project-profile.json \
--repo-path /path/to/repo
刷新主要更新 Project State 的 Git 基线。Project Profile 的稳定绑定哈希只在项目身份或治理边界变化时改变。
6. 项目隔离¶
每个项目必须使用独立 Project ID 和目录。禁止:
- 复制 A 项目的 Profile 给 B 项目;
- 复用其他项目的 Approval;
- 把其他项目的接口、表结构、凭据和结论写入当前 Project Memory;
- 在同一个任务状态中切换仓库根目录;
- 依赖项目名称相同而忽略 Remote 和路径验证。