lanrtop 02b9f1ec36 feat(delivery): observe production revision with dual evidence

Read project-owned production profile, verify Gitea deploy context and public version probe, and surface explicit degraded states.

Feature-Confirmed: true

2026-09-23 10:37:07 +09:00

5.9 KiB

Raw Blame History

Git 工作流 — AI Agent 操作指南

把此文件粘贴给任何 AI Agent，让它了解本项目的 git 工作方式。由炼境接入包分发。 ONBOARDING_MANAGED 标记块由炼境版本化管理（重跑接入包可原位升级），块外可自由补充项目特有约定。

⚠️ 本块由炼境版本化托管，升级时整块原位覆盖——项目定制请写到块外，块内手改必丢。

分支策略（复杂度感知）

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），对应项目功能模块。

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 一次提交所有。按功能分批：

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 工具：

{ "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；仅在用户明确确认本次合并后调用：

{
  "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 自行推断。

常用命令

git status --short
git log --oneline -10
git reset --soft HEAD~1   # 撤销最后一次 commit（保留改动）

5.9 KiB Raw Blame History Unescape Escape