02b9f1ec36
Read project-owned production profile, verify Gitea deploy context and public version probe, and surface explicit degraded states. Feature-Confirmed: true
138 lines
5.9 KiB
Markdown
138 lines
5.9 KiB
Markdown
# Git 工作流 — AI Agent 操作指南
|
||
|
||
> 把此文件粘贴给任何 AI Agent，让它了解本项目的 git 工作方式。由炼境接入包分发。
|
||
> `ONBOARDING_MANAGED` 标记块由炼境版本化管理（重跑接入包可原位升级），块外可自由补充项目特有约定。
|
||
|
||
<!-- ONBOARDING_MANAGED_START version="1.7.0" -->
|
||
> ⚠️ 本块由炼境版本化托管，升级时**整块原位覆盖**——项目定制请写到块外，块内手改必丢。
|
||
|
||
## 分支策略（复杂度感知）
|
||
|
||
```
|
||
main/master ← 主分支，保持稳定
|
||
↑
|
||
├── 简单改动 → 直接 push main/master
|
||
└── 功能性改动 → feat/<name> 分支 → PR → main/master
|
||
```
|
||
|
||
**简单改动（直接推主分支）**：bug fix、chore、docs、style、单文件小改，行为对外无变化。
|
||
|
||
**功能性改动（开 feat/* 分支 + PR）**：新功能、重构、涉及多模块的 refactor。由 agent 根据改动文件数和性质自判，无需蓝图标签。
|
||
|
||
分支命名：`feat/<功能简述>`，如 `feat/login-sms`、`feat/order-pagination`。
|
||
|
||
## Commit 规范（lefthook 强制）
|
||
|
||
格式：`<type>(<scope>): <描述>`
|
||
|
||
| type | 用途 |
|
||
|------|------|
|
||
| `feat` | 新功能 |
|
||
| `fix` | Bug 修复 |
|
||
| `chore` | 配置、依赖、脚本 |
|
||
| `docs` | 文档 |
|
||
| `refactor` | 重构（不改功能） |
|
||
| `ci` | CI 配置 |
|
||
| `perf` | 性能优化 |
|
||
| `style` | 代码格式 |
|
||
| `test` | 测试 |
|
||
|
||
`scope` 用「模块/子模块」二级结构（如 `auth/login`、`api/user`、`db/order`），对应项目功能模块。
|
||
|
||
```bash
|
||
git commit -m "feat(auth/login): 新增手机号登录"
|
||
git commit -m "fix(api/user): 修正分页 off-by-one"
|
||
```
|
||
|
||
> 炼境会解析这些 commit 的 type/scope 作为飞轮数据：`fix` 计入返工率、`scope` 归到模块。
|
||
> **commit 写得越规范，飞轮数据越准。**
|
||
|
||
## Rules-Applied trailer（规则命中回传）
|
||
|
||
若本次任务中触发过项目约定规则（见项目 CONVENTIONS.md 或 `.blueprint/CONVENTIONS.md`），
|
||
在 commit message 末尾追加一行 trailer（与正文空行分隔）：
|
||
|
||
```
|
||
feat(auth/login): 新增手机号登录
|
||
|
||
Rules-Applied: R01,R05
|
||
```
|
||
|
||
- 只记录**真实触发**（主动检查或执行）的规则，未触发则整行省略
|
||
- 炼境自动解析此 trailer 做「规则命中 × 返工」交叉统计，是 CONVENTIONS 置信度进化的数据来源
|
||
- 凭空罗列会污染数据——宁缺毋滥
|
||
|
||
## 一个 commit = 一件独立的事
|
||
|
||
不要 `git add -A` 一次提交所有。按功能分批：
|
||
|
||
```bash
|
||
git add <相关文件>
|
||
git commit -m "feat(模块): 一件事"
|
||
```
|
||
|
||
## PR 大小控制
|
||
|
||
PR 别攒太大（建议每 3~5 个 commit 或几百行内就开一次），否则 CI code review 易超时失效。
|
||
「所有检测通过」≠ 代码被审查过——大 PR 即使 CI 全绿，review 可能已静默失效。
|
||
|
||
## PR 创建（炼境托管项目）
|
||
|
||
本项目由炼境管理；`.lian-jing/context.json` 是 `project_id` 的唯一来源。Codex 使用项目级 `.codex/config.toml` 发现 MCP（项目须受信任）；`.claude/liangjing.json` 仅是旧项目的 Claude 兼容投影。
|
||
炼境 MCP 是单一全局服务器 `lian-jing`，所有工具显式传 `project_id` 寻址，无需 group_id。
|
||
|
||
**推送分支后，通过炼境 MCP 创建 PR，禁止用 curl + git credential fill 提取 token：**
|
||
|
||
```
|
||
1. Read .lian-jing/context.json → 取出 project_id
|
||
2. 调用 MCP 工具 create_pull_request：
|
||
{ "project_id": "<id>", "head": "feat/<name>", "base": "main",
|
||
"title": "<Conventional Commits 格式>", "body": "<变更摘要>" }
|
||
3. 炼境内部用存储的 Gitea 凭证调 API，返回 pr_url
|
||
```
|
||
|
||
若炼境未运行（MCP 不可用），降级方案：去 Gitea 网页手动创建 PR。
|
||
|
||
> 若只存在 `.claude/liangjing.json`，先调用 `inject_mcp(project_id)` 迁移到 canonical context；禁止将 Codex 用户级插件、客户端项目 UI 或全局配置当作项目身份来源。
|
||
|
||
## 交付状态（炼境托管项目）
|
||
|
||
在准备开 PR、合并 PR 或排查部署问题时，先调用 MCP 工具：
|
||
|
||
```json
|
||
{ "project_id": "<id>" }
|
||
```
|
||
|
||
工具名为 `get_delivery_status`，返回本地工作区与最近 commit SHA、当前分支的 Gitea PR、CI、review 和已知的部署/健康证据。
|
||
|
||
- `unknown`：炼境尚未获得该项证据，**不是成功**；例如 CI 成功不能代替 production 健康。
|
||
- `unavailable`：对应外部来源暂时不可达；保留本地验证与 Gitea 网页作为降级路径。
|
||
- `not_configured`：项目尚未声明 `.lian-jing/capabilities.yaml` 的 production delivery profile；这是正常的可选接入状态，不代表部署失败。
|
||
- `deployed` 仅表示 Gitea 部署 context 成功、公开版本探针健康且运行 SHA 与默认分支目标 SHA 完全一致；`drifted` 表示运行 SHA 不一致。技术健康不替代业务验收。
|
||
- production profile 由项目维护，炼境接入包不会覆盖；只声明公开 HTTP(S) JSON URL、精确 Gitea context 和字段名，不放凭证或命令。
|
||
- 结果是交付上下文，不替代项目自己的测试、业务验收或发布决定。
|
||
|
||
## PR 合并（炼境托管项目）
|
||
|
||
合并属于高影响操作，Agent 必须先读取交付状态并向用户展示 PR 编号、完整 head SHA、CI 与 review；仅在用户明确确认本次合并后调用：
|
||
|
||
```json
|
||
{
|
||
"project_id": "<id>",
|
||
"pr_number": 123,
|
||
"expected_head_sha": "<完整 40 位 SHA>",
|
||
"confirmed": true
|
||
}
|
||
```
|
||
|
||
工具名为 `merge_pull_request`。能力本体会重新读取远端状态；PR 非 open、head SHA 漂移、CI 未通过、review 请求修改或任一门禁来源不可用时均拒绝合并。合并成功后再次调用 `get_delivery_status` 读取真实结果。`confirmed=true` 只能来自当前用户对该 PR 与 SHA 的明确确认，不能由 Agent 自行推断。
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
git status --short
|
||
git log --oneline -10
|
||
git reset --soft HEAD~1 # 撤销最后一次 commit（保留改动）
|
||
```
|
||
<!-- ONBOARDING_MANAGED_END -->
|