CodeBuddy

Hy3 preview

## 26年蒸蚌特权准备中...

26年蒸蚌特权准备中，顶级组织自由创建暂时关闭，节后放开，好好过节

电商 mini 演示项目 + .codebuddy 框架（rules/skills/feedback）— 沉淀了 Spring Boot 3 + Vue 3 全栈开发的规则与经验教训

anta-workshopdemo

docs(skills): Agent Harness v2 规格 + skills 依赖图 + 契约校验

阶段 2 - PR 5：把 skills 的协作从文档描述升级为机器可读契约。

解决问题：

- v1 _meta.json 只有 name/description/version/location 4 字段

- 触发条件只在 description 自然语言，Agent 命中率低

- skills 之间的依赖关系没有机器可读声明

- 输入输出 / 副作用 / 成本无契约，风险不可预估

产出：

1. skills/_AGENT_HARNESS_SPEC.md（规格文档）

   v2 字段规格：triggers / dependencies / inputs / outputs /

   side_effects（fs/net/db/git/external_api 五维）/ idempotent /

   requires_confirmation / cost（时长+LLM+复杂度）

   派生自 meta-principles §原则 5（契约优先）

2. skills/_schema.json（JSON Schema）

   Draft-7 规范，含字段类型、enum、pattern、required 约束

   新增 parameter / parameter_with_default 子 schema

3. 9 个 _meta.json 全部升级到 v2（version: 2.0.0）

   - requirement-workflow（high/30min，调用 4 个下级 skill）

   - requirement-analysis（low/30s，auto_trigger=true，幂等）

   - scaffold（low/10s，写文件，需确认）

   - code-review（medium/2min，只读，幂等）

   - api-docs（low/15s，写文件，需确认）

   - cicd-pipeline（medium/20s，写文件，需确认）

   - changelog（trivial/5s，写文件，需确认）

   - tapd（trivial/3s，调外部 API，需确认）

   - skill-creator（trivial/5s，写文件，需确认）

4. skills/SKILLS.md（机器可读依赖图 + 人类可读索引）

   - §一 清单（9 行总览表，含复杂度/时长/幂等/副作用）

   - §二 依赖关系 ASCII 图

   - §三 4 种调用路径场景

   - §四 触发关键词速查

   - §五 副作用三分类（只读/写文件/调外部 API）

   - §六 成本分级速查

   - §七 维护约束

5. scripts/validate_skill_meta.py（真实契约校验）

   - JSON Schema 校验所有 _meta.json

   - 交叉规则：写/推/外部 API 副作用必须 requires_confirmation=true

   容器化验证通过：9/9 合规

6. LESSONS.md

   §二 反模式表新增 2 条（#4 _meta.json 缺契约、#5 skills 调用靠口头）

   §三 资产清单新增 3 条（SKILLS.md / v2 规格 / 校验脚本）

7. .codebuddy/README.md

   Skills 索引指向 SKILLS.md 详细依赖图 + v2 规格文档

   列出 6 个关键字段

真实验证（元原则 1 + 5 双重自证）：

- 容器化 python:3.12-slim + jsonschema 跑校验

- 第一次发现 api-docs / changelog 两处违规（写文件未要求确认）

- 修复后 9/9 通过

- lint 0 错误


feat(ci): 接入 CNB 流水线 + 7 个 POSIX shell 自举检查脚本

docs(checkpoint): 闭环 T-04 + 轮次 8 档案 + #16 阻塞升级文档同步

§一 上次更新 → PR #33
§一 P1 #16 从 '16 处命中 / 观测型' 升级为
       '29 处命中 / 0 真实残留 / 阻塞型（自动分类）'
    阈值描述新增「已棘轮到顶（≤ 0）」标注
§二 资产规模新增 abstraction_check.py（2 个 Python 辅助脚本）
§三 PR 总览新增 #33
§四 新增「轮次 8 · T-04 闭环」完整档案：
  - 改动清单：abstraction_check.py 7 条 L1~L7 分类规则 + shell 包装阻塞化
  - 计数口径升级：行级（16）→ 匹配级（29），精确化而非真的涨
  - 本地正反双向测试：1 正（29/0）+ 2 反（精确识破 2/4 residual）
  - 双事实源累积到 4 处：新 #16 #4 位置由 report-abstraction.sh
    --max-residual=0 与 CHECKPOINT §一 保底 ≤ 0 互锁
  - 4 条学到的东西：
      * 观测型 → 阻塞型升级的前提（分类精度 + 反向测试 + 现状为零）
      * 按行计数 → 按匹配计数是健康的度量精确化
      * 白名单 vs 启发式规则必须分层共存
      * 棘轮第二次真实上调（#12 之后，#16 从 ≤ 2 到 ≤ 0）
§五 T-04 划线闭环

LESSONS §三 自举 CI 条目更新：8 脚本 + 2 个 Python 辅助 + 四处双事实源

governance/quality-dashboard.md §7.2 #16 测量命令：
  - 主推 abstraction_check.py（新推荐）
  - 保留原 grep 命令作对照
  - 新增 L1~L7 分类规则注释 + 新项目迁移指南

.cnb.yml stage 名：p1-abstraction-observe → p1-abstraction-check
  （两处同时改动由 verify-yml-consistency.sh 守门验证）
scripts/ci/README.md 脚本清单同步（#16 从 '❌ 否' → '✅ 是'）

派生自 meta-principles.md §原则 2（守门员必须反向测试）、§原则 3
（棘轮质量阈值——#16 第二次真实上调）、§原则 4（抽象化自验证）、
§原则 5（契约优先——双事实源同步）


PR-E：方向 F1 四 PR 经验回写——LESSONS B13/B14 + 棘轮口径区分 + CNB 坑点实证清单（轮次 14-e）

docs(share): workshop-share.md 新增 M9·CI 平台坑点实证清单（第 9 种治理模式）

关闭 CHECKPOINT §五 T-Q3-03——把目标项目方向 F1 四 PR 演化换来的 CNB
坑点，从 skills/cicd-pipeline/SKILL.md 的"使用指引层"升级到
workshop-share.md 的"治理模式层"——让其他团队 Leader 也能看懂
"为什么要把平台坑点收编为一等资产"。

改动：

1. §一 TL;DR 表扩展 8 行 → 9 行
   - PR 数 "15 PR" → "23 PR"（反映 Q2 + Q3 累计）
   - 新增 M9 行：CI 平台坑点实证清单
   - 反直觉认识新增一条：M9 的生存价值——4 个 fail PR 换来的实证
     不能只消化在源代码里

2. §四 标题 "八种模式" → "九种模式" + M9 完整子节

   M9 · CI 平台坑点实证清单（Platform Pitfalls as First-Class Assets）

   起因：4 PR 演化实证表（附目标项目 #3~#7 演化）
     #3 假绿 → #4 推断修 → #5 诊断 → #6 装 CLI → #7 根治

   4 条核心发现（官方文档未说明）：
   - services:[docker] 强制忽略 image: 字段
   - services:[docker] 不注入 CLI 也不设 DOCKER_HOST
   - Stage 耗时是识别静默跳过的关键信号
   - default-build-env 实际内容：Java/Maven ✅ / Docker CLI ❌

   把坑点本身作为资产——对比表：
     普通经验笔记 vs M9 平台坑点实证清单
     - 写在私有 doc → 写在 skills/ 被 scaffold 引用
     - 下一个项目重新踩 → 下一个项目直接跳过
     - "我记得 CNB 有个问题" → "坑点 1: 证据 env 输出"

   4 条关键约束（派生自 M2 + M4）：
   - 必须配实证锚点（env 输出/PR SN/stage 耗时）
   - 必须与 CHECKPOINT 某轮次关联
   - 推荐随平台扩充独立子节（GitHub Actions/GitLab CI/...）
   - 推荐坑点失效时标注"历史坑点"不删除

   3 条反模式：
   - 我们换脚本绕过了但没记录 bug
   - 那是平台方的问题不是我们的
   - 写在 commit message 里（git log 不是知识库）

   与 M8 的关系：
     对已发生的坑要收编（M9），对未验证的假说才克制（M8）
     两者合成"对不同证据强度采取不同机制化力度"

M9 的分层定位：
  使用指引层（PR-E 已完成）：skills/cicd-pipeline/SKILL.md
    受众：本项目 scaffold 使用者
    内容：具体坑点条目 + 决策树

  治理模式层（本 PR 完成）：docs/workshop-share.md §四 M9
    受众：其他团队 Leader
    内容：把"收编平台坑点作为资产"本身作为治理模式

  前者讲"怎么用"，后者讲"为什么要这样用"——同一知识在不同层
  有不同价值，关键是各有受众。

本地 9/9 CI stages 全绿 + 0 lint + #16 仍 45 legit / 0 residual。

规则自举第 6 次实证：docs/ 天然在 scope（rules + governance）
之外放行——不是"守门员识别能力"而是"scope 划分本身的健康度"。
健康 scope 让输出向文档（docs/）和约束向文档（rules/governance）
天然隔离。累计 6 次 = 3 阻塞 + 3 放行（连续 3 次合规放行）。

派生自 meta-principles §原则 4（抽象化——把具体坑点升级为模式
是抽象层级的跃迁）+ §原则 5（契约——M9 作为"模式"本身是
跨团队的契约，约定"什么是好的坑点记录方式"）+ LESSONS §二
信号欺骗家族（B13 的正面消化：把 4 fail PR 的认知沉淀）。

Refs: 目标项目 anta-newproject-demo PR #4~#7 /
      源仓库 PR-E（skills 层沉淀）/
      CHECKPOINT §四 轮次 15-b / T-Q3-03 闭环


PR-G：workshop-share.md 新增 M9·CI 平台坑点实证清单——第 9 种治理模式外显（轮次 15-b）

PR-H：M9 消费端首次实证回写——双向 loop 3 步环闭合（轮次 15-c）

## 背景

PR #1 已以 merge commit 合入 main，但 PR #2（FB-06）和 PR #3（B13/B14/B15）的 base 分别指向中间分支 foundation-setup 和 fb-06-api-contract-validation。CNB 把它们标记为 merged，但实际上只是合进了中间分支，main 里**还没有**这些成果。

本 PR 把 `feature/order-payment-fixes`（包含 PR #2 + PR #3 的全部 11 个 commit）一次性合入 main。

## 合入 main 的 11 个 commit

### FB-06 相关（6 个）
- `refactor(payment)` 删除 scaffold payment 死代码
- `fix(frontend)` inventory 路径复数修正
- `test(backend)` OpenApiExportTest 导出契约
- `feat(frontend)` typed apiClient + 契约校验脚本
- `chore(ci)` .cnb.yml 6 阶段流水线
- `docs(framework)` FB-06 方案沉淀到 api-docs skill

### B13/B14/B15 业务层修复（5 个）
- `feat(order)` OrderItem Entity / Mapper
- `fix(payment)` PaymentCreateResultVO + handleCallback 状态机化
- `fix(order)` 下单写明细 + 取消回退库存
- `test(order)` 新增 2 个 B14 专项测试
- `docs(checkpoint)` 第 10 轮记录

## 验证

- ✅ 真实编译 BUILD SUCCESS（Docker JDK 17）
- ✅ 单元测试 15/15 PASS
- ✅ `.codebuddy/` lint 0 错误
- ✅ 契约校验脚本首次运行即抓出 2 处真实违规并修复
- ✅ CHECKPOINT 未完成清单已清零（仅剩 ac3 CI 验证一项依赖 Linux runner）

## 合并后状态

合入后 main 将包含：
- foundation-setup 的全部 10 个 commit（已在 PR #1 中合入）
- FB-06 的 6 个 commit（首次进入 main）
- B13/B14/B15 的 5 个 commit（首次进入 main）

main 分支将真正成为所有工作的单一事实源。

背景

合入 main 的 11 个 commit

FB-06 相关（6 个）

B13/B14/B15 业务层修复（5 个）

验证

合并后状态

Successfully merged and closed