⌘ K
四仓脚手架：选仓、拉取与新项目开发
给产品同事的新项目操作指南：从哪里找脚手架、没权限找谁、代码放在哪里、怎样交给 AI 开发，以及怎样交到研发手里上线。
公司新项目沿用四仓的固定技术栈。本指南依据 2026 年 10 月 21 日检出的四仓 README、AGENTS.md 和团队确认的权限处理方式整理；具体启动命令、分支与部署方式以目标项目当前约定为准。
先记住三个位置
| 位置 | 是什么 | 你要做什么 |
|---|---|---|
| 脚手架源仓库 | 公司 Codeup 的 Base/xt-platform-* 四个仓库，共用的工程起点 |
从下面的地址查看、拉取。没有权限就找对应开发。 |
| 你电脑上的项目目录 | 从脚手架拉下来的本地代码，Agent 在这里修改和运行 | 将四个仓库放在同一项目父目录下，分别保留各自的 Git 仓库。 |
| 新项目仓库 | 公司 Codeup 中为这个产品新建的四个目标仓库 | 由对应开发确认所属代码组、地址和分支；之后把本地改动推到这里。 |
git clone 是把源代码拉到电脑；origin 是本地代码接下来同步的远端地址；git push 才会把提交传到远端。拉下脚手架后，要先把 origin 换成新项目仓库。
现场演示：用“活动报名”走一遍
示例范围：用户在浏览器报名，运营在管理端审核，用户能查到结果。它用于说明操作顺序，不表示已经创建或上线了一个活动产品。
| 步骤 | 屏幕上实际展示什么 | 完成时应看到什么 |
|---|---|---|
| 1. 找入口 | 打开本指南，点击下方四个源仓库链接 | 能看到代码文件与 README。 |
| 2. 拿权限 | 确认公司账号、仓库读取及新仓库写入权限 | 网页能看、SSH 能拉；缺权限就找对应开发。 |
| 3. 确认场景 | 说明活动报名的用户端、管理端、账号与数据需求 | 首期使用 Java + Web + admin，uni-app 暂不开发和发布。 |
| 4. 建新仓库 | 打开对应开发指定的新项目代码组和四个目标仓库 | 有四个真实目标地址、默认分支和协作成员。 |
| 5. 初始化 | 拉取四仓、更换各自远端、首次推送 | 本地远端和 Codeup 页面都指向新项目。 |
| 6. 交给 Agent | 提供需求、项目目录、规范地址，先启动现有工程 | 基线能构建、能运行，Agent 列出真实缺口。 |
| 7. 做通流程 | 用户提交 → 后台审核 → 用户查询 | 真实接口保存，刷新和重新登录后结果仍在。 |
| 8. 交付上线 | 查看提交、测试地址、验收记录和发布版本 | 研发能按记录发布，产品在目标环境走完同一流程。 |
现场开始前先与对应开发准备好演示账号、新项目仓库和测试环境。依赖安装、构建、发布可以展示事先真实执行留下的结果，说明哪些步骤现场操作、哪些已提前完成；不把示例地址、模拟数据或本地运行当作已上线。
1. 找到脚手架，确认访问权限
打开下方仓库网页，用已加入公司云效组织的账号登录。没有权限就找对应开发开通，同时说明你要做的产品、需要的仓库和使用目的。无需申请源仓库写入权限来开发自己的产品。
可以复制这段发给对应开发：
我要用四仓脚手架开发【产品名称】，首期场景是【用户端、管理端、核心流程】。
我的云效账号是【账号】，当前无法访问【仓库链接 / 错误现象】。
请帮我开通脚手架读取与克隆权限，并确认新项目所属代码组、四个目标仓库地址、默认分支，以及我的开发分支推送权限。
| 现象 | 下一步 |
|---|---|
| 仓库网页无权限或找不到 | 核对账号和公司组织，把完整链接交给对应开发确认仓库权限。 |
| 网页可看，但 SSH 拉取失败 | 按官方说明配置本机 SSH 公钥到同一个云效账号；仍失败请对应开发核对克隆权限。SSH 公钥配置不会自动授予仓库权限。 |
| 可以拉取，不能推到新项目 | 让对应开发核对新项目成员权限、远端地址和目标分支规则；受保护分支按项目流程提交合并请求。 |
| 无法创建新项目仓库 | 请对应开发在确定的代码组下创建，再把四个地址交给你。 |
操作参考：Codeup 配置 SSH 密钥、代码组与代码库权限。
2. 按场景确定首期开发哪些仓库
四个脚手架分别复制为新项目的四个仓库；“选择”指根据本次需求决定先修改、验证和交付哪些仓库，不是重新选技术栈。
| 需求落点 | 对应仓库 | 同时检查 |
|---|---|---|
| API、身份权限、业务规则、数据库 | xt-platform-java |
哪些前端要调用新接口，以及数据变更如何交付。 |
| 运营/管理页面 | xt-platform-admin |
Java 的 /admin-api 契约、菜单和服务端权限。 |
| 电脑或手机浏览器的用户前台 | xt-platform-web |
Java 提供的用户端 API、认证方式和 Nuxt SSR 部署。 |
| H5、微信小程序或 App 前台 | xt-platform-uniApp |
Java API、平台登录与对应平台构建。 |
例如新增“用户提交申请、运营审核”：Java 负责申请状态、权限和数据；Web 或 uni-app 实现用户提交，admin 实现审核。若首期没有 App 页面，仍可保留 uni-app 新项目仓库，但不做无需求的页面或发布。实际需求先于仓库数量；不要把业务逻辑分别写在多个前端。
四个脚手架源仓库地址
网页地址用于查看代码，SSH 地址用于 git clone。这些是脚手架源仓库，新项目应另建自己的四个目标仓库，并将各本地仓库的 origin 改到对应目标地址。
| 仓库 | 网页地址 | SSH 地址 |
|---|---|---|
xt-platform-java |
查看后端仓库 | git@codeup.aliyun.com:696a12a07a1ed8d3da00f471/Base/xt-platform-java.git |
xt-platform-admin |
查看管理端仓库 | git@codeup.aliyun.com:696a12a07a1ed8d3da00f471/Base/xt-platform-admin.git |
xt-platform-web |
查看浏览器前台仓库 | git@codeup.aliyun.com:696a12a07a1ed8d3da00f471/Base/xt-platform-web.git |
xt-platform-uniApp |
查看多端前台仓库 | git@codeup.aliyun.com:696a12a07a1ed8d3da00f471/Base/xt-platform-uniApp.git |
3. 先确定新项目仓库放在哪里
新项目继续放在公司 Codeup 中，由对应开发确认的项目代码组。Base 中上面的四个地址用于取脚手架；自己的产品代码放到新项目目标仓库。代码组没有在本指南中统一指定，不要从示例猜一个真实位置。
有创建权限时，在对应开发确认的位置新建四个空仓库；无创建权限时请对应开发代建。按当前项目命名规则填写名称与成员。复制已有脚手架历史时，目标仓库先不初始化 README 或其他文件，避免出现两套初始历史。平台操作见 Codeup 快速入门。
在项目 README 中记录下面这张表。event-* 只是活动报名示例名，实际网页和 SSH 地址必须从新建仓库页面复制。
| 脚手架来源 | 新项目仓库示例名 | 开发前要填齐 |
|---|---|---|
xt-platform-java |
event-java |
网页地址、SSH 地址、默认分支 |
xt-platform-admin |
event-admin |
网页地址、SSH 地址、默认分支 |
xt-platform-web |
event-web |
网页地址、SSH 地址、默认分支 |
xt-platform-uniApp |
event-uniApp |
网页地址、SSH 地址、默认分支 |
这张表是之后找代码和交接给研发的入口。四个远端准备齐全，开发和部署只覆盖首期实际需要的端。
4. 拉取四个脚手架到本地
在新项目的本地父目录执行。以下为脚手架的 SSH 源地址；your-project 是示例目录名，执行前换成实际名称，且该目录应为空或不存在。不要把脚手架仓库直接当新项目的远端长期使用。
mkdir your-project
cd your-project
git clone git@codeup.aliyun.com:696a12a07a1ed8d3da00f471/Base/xt-platform-java.git
git clone git@codeup.aliyun.com:696a12a07a1ed8d3da00f471/Base/xt-platform-admin.git
git clone git@codeup.aliyun.com:696a12a07a1ed8d3da00f471/Base/xt-platform-web.git
git clone git@codeup.aliyun.com:696a12a07a1ed8d3da00f471/Base/xt-platform-uniApp.git
四个目录是四个独立 Git 仓库。首次打开时分别运行 git status -sb、git log -1 --oneline、git remote -v，确认所处分支、修订和源地址。脚手架当前默认分支并不相同；不能假定四仓都是 main。不要在本地复用同一套 Node/pnpm 版本：各仓版本按当前 README 和锁文件准备。
5. 把远端改为新项目仓库，再首次推送
先由项目负责人确定四个新项目仓库的地址、默认分支和访问权限。目标通常是四个对应的空仓库；不要把四份代码推到同一 Git 仓库，也不要改写脚手架源仓库。进入每个本地目录，把 origin 改为对应的新地址：
cd xt-platform-java
git remote set-url origin 'git@codeup.aliyun.com:组织/项目/新项目-java.git'
git remote -v
git status -sb
对 xt-platform-admin、xt-platform-web、xt-platform-uniApp 分别重复，替换为各自的新项目仓库地址。示例中的“组织/项目/新项目”必须换成真实地址；git remote -v 的 fetch 和 push 地址都应指向该仓库。set-url 只修改本地 Git 远端，不会推送代码，也不会修改脚手架源仓库。若想保留源地址供以后比较，可先记录在项目文档中；后续更新应先审阅差异，不能无条件合并脚手架的新提交。
只有确认目标仓库为空、分支策略明确且已获得推送授权后，才执行首次推送。若目标仓库已有提交，先核对其历史和默认分支，不能用 --force 覆盖。下面仅适用于对应开发已确定新项目默认分支为 main，且本地不存在冲突的其他 main 分支时：
git branch -m main
git push -u origin main
git remote -v
git status -sb
这里把本地分支与新远端分支对齐；main 不是四个脚手架的统一默认分支。若项目用其他分支名，按约定替换。若默认分支受保护，由对应开发完成初始化，再按项目分支流程开发。之后打开新项目网页，确认四份代码分别出现且提交一致，并在平台确认默认分支。
6. 让 Agent 先读规则、启动工程，再开发
- 分别阅读涉及仓库的
README.md、根目录AGENTS.md、相关开发文档和按任务需要的.agents/skills/。仓库本地规则优先于本站概述。 - 按固定技术栈保留原有框架、构建工具和请求层；仅在需求涉及的仓库增加业务代码。后端先明确规则、权限和数据，再对接页面；不要把前端演示数据视作后端已实现。
- 按各仓锁文件安装与验证。Java 以 Maven 构建；admin、web、uni-app 各有自己的 Node/pnpm 基线。具体命令取当前仓库 README，不复制其他仓库的版本和脚本。
- 联调真实 API，核对前后端接口、身份/租户、失败状态与持久化结果。管理端是静态 SPA；Web 是需要 Node 运行的 Nuxt SSR；uni-app 按目标平台验证。跨仓边界见四仓项目蓝图。
- 交付时记录四个新项目仓库地址与修订、实际涉及的端、构建结果、配置需求、数据库变更、联调证据及未验证的平台或环境。没有完成联调时如实说明。
脚手架的阶段性能力和缺口见脚手架当前能力与待联调事项。
把实际信息填进下面的提示，再交给能访问项目目录的 Agent：
我要开发【产品名称】，项目父目录是【本机绝对路径】。
四个新项目仓库地址与默认分支见【项目 README / 地址表】。
先阅读 https://docs.tzxys.cn/llms.txt 和四仓起步指南：
https://docs.tzxys.cn/content/engineering/scaffolds/four-repository-start.md
再读取各仓 README.md、AGENTS.md、现有实现及与任务相关的规范。
固定使用四仓现有技术栈。先检查四个 origin 都指向新项目，按各仓要求启动并记录构建结果。
首期是浏览器活动报名：用户登录提交报名，运营审核，用户查询结果。
涉及 Java、Web、admin；uni-app 本期不开发、不发布。
先说明账号来源、数据归属、接口、配置依赖和缺口，再实现这一条真实流程。
从真实接口保存，补齐权限、加载、空态、失败与重复提交处理。
完成后给出改动仓库、提交、运行方法、验证结果和待研发协助的事项。
环境地址和授权信息缺失时列出需要对应开发提供的内容，不自行编造。
产品同事负责确认流程和结果，对应开发提供账号接入、接口、环境与部署边界，Agent 按这些信息执行。脚手架能启动只是基线；账号、业务接口和数据仍要按新产品接通。
7. 用真实流程验收第一轮结果
活动报名示例可以按下面顺序现场演示：
- 用户提交：用测试账号填写并提交一条报名。页面显示服务端返回的结果；失败时不能显示成功。
- 后台查到：进入新项目管理端，找到同一条报名，核对账号、活动和状态。
- 运营处理：有权限的运营账号审核报名；无权限账号不能执行该操作。
- 用户读回：用户页面刷新、退出并重新登录，仍能查询到审核结果；换另一账号不能看到别人的记录。
- 异常与规模：核对重复提交和接口失败提示；按预期数据量检查列表、图片与请求，不只用几条假数据验收。
保留测试环境、版本、操作结果和未通过项。本地完成后还要在目标测试环境再走一遍；涉及小程序或 App 的项目要补目标平台验证。
8. 交给研发、测试部署，再上线
产品在新项目仓库持续协作，交付入口应是仓库与提交版本。进入团队约定的审查和发布流程前，至少交齐：
| 交付项 | 要写清什么 |
|---|---|
| 代码与范围 | 四个新项目地址、分支与提交；本次涉及哪些端。 |
| 运行与配置 | 已验证的安装、构建和启动方法；所需环境变量名、账号和资源依赖。凭据按团队方式交接。 |
| 数据与内容 | 数据库变更、初始化数据、图片或音频如何导入目标环境。 |
| 验收 | 核心真实流程、权限与失败场景的结果，以及未通过项。 |
| 发布与恢复 | 目标环境、域名、发布负责人、本次版本、日志和回退方式。 |
对应开发检查代码和配置，按现有流程发布到测试环境；产品在测试地址走完上面的真实流程。确认首期范围通过后，由项目约定的负责人发布生产，再验证登录、提交、后台处理和结果读回，记录本次版本。
公司四仓的运行方式不同：Java 需要后端运行环境，admin 是静态站点，Web 是 Nuxt SSR 的 Node 服务，uni-app 按实际平台构建。一个前端页面能打开，不能代替其余服务、配置、数据和权限的交付。具体职责与边界见四仓项目蓝图。