Skip to content

feat(skills)!: Agent Skill 以仓库目录分发,移除 skills 子命令 - #35

Merged
kooksee merged 15 commits into
mainfrom
chore/agents-skills
Nov 4, 2026
Merged

kooksee merged 15 commits into
mainfrom
chore/agents-skills

Conversation

@kooksee

@kooksee kooksee commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

变更说明

protobuild 的对外 Agent Skill 从 CLI 内联模板(protobuild skills)迁移为仓库真实目录 skills/protobuild/,经 npx skills add pubgo/protobuild(支持 -g)分发;删除 skills 子命令并加防漂移守卫测试。

  • 新增 skills/protobuild/:SKILL.md(渐进披露主入口,覆盖 init/vendor/gen/检查/诊断全流程)+ references/(commands.md 16 命令速查、config.md 配置要点、troubleshooting.md 故障修法)+ agents/openai.yaml
  • 新增守卫测试 TestCommandsDocumentedInSkillRefs:遍历 Main().Children 断言每个子命令名出现于 commands.md,漏同步文档时 CI 红(已负向验证非摆设)
  • 删除 newSkillsCommand/defaultSkillContent/defaultOpenAIContent 及辅助函数;README 移除 skills 行
  • 文档同步:AGENT_SKILL.md 接入方式改为 npx/拷贝双路径 + 迁移提示;AGENTS.md 三件套→两件套并首次入库;INDEX 补技能真源入口
  • 附独立 style: 提交(golangci-lint issues.fix 对无关文件的自动修复)

设计:docs/superpowers/specs/2026-11-03-skill-directory-design.md;计划:docs/superpowers/plans/2026-11-03-skill-directory.md

变更类型

  • 破坏性变更(protobuild skills 子命令移除,spec 决策:纯删除、无 tombstone)
  • 缺陷修复
  • 新功能
  • 文档更新
  • 配置变更
  • 代码重构
  • 风格调整
  • 性能优化
  • 测试相关

关联问题

无(技能模板漂移治理,源自本轮 agents/skills 完善工作)

提交前检查清单

关键项

  • 无需求不匹配问题(REQ)—— 对照已批准 spec 逐条验收
  • 无逻辑缺陷(LOGI)—— 整分支 fresh-eyes 评审:0 Critical;2 Important 已修(init 模板大小写、doctor --fix 不代跑 vendor,均有源码/复现证据)
  • 无安全问题(SEC)
  • 无认证授权问题(AUTH)

高优先级项

  • 设计合理(DSN)—— 单一真源,双源漂移病根已机制性封堵
  • 错误处理健壮(RBST)/ 事务(TRANS)/ 并发(CONC)/ 性能(PERF)—— 本次为删除+文档,无新执行路径

质量项

  • 代码可维护 / 无不必要的耦合 / 可读 / 无重复代码 / 命名清晰

测试项

  • 已补充或更新单元测试(守卫测试 + 负向验证)
  • 集成测试通过(task all: vet→lint→test→build 全绿)
  • 已完成手动验证(go run . --help 无 skills;skills-ref validate 通过;init -t BASIC/basic 复现对照)

文档项

  • 已补充必要注释;README 已更新;相关文档已更新

补充说明

  1. npx skills add pubgo/protobuild 真实安装依赖默认分支,合并后需补跑一次并在本 PR 备注留痕(本地已用 skills-ref validate 验证结构)。
  2. 曾用 protobuild skills 生成 .agents/skills/protobuild/ 的用户:旧文件与新技能同名可能遮蔽新内容,删除指引见 AGENT_SKILL.md 迁移提示。
  3. 评审遗留 minor(不在本 PR 处理):守卫单向、breaking --path 未列、未来加 *.svg 图标需 git add -f。

@kooksee

kooksee commented Nov 3, 2026

Copy link
Copy Markdown
Contributor Author

追加提交 08f3e91 fix(cli): log top-level errors without goroutine stack dump:顶层 CLI 错误原先走 funk assert.Exit(硬编码 debug.PrintStack()),普通操作错误(如本仓库已存在 protobuf.yaml 时跑 init)会附带整段 goroutine dump,形似崩溃。现改为 protobuild.ExitOnError:单行 ERROR 日志 + exit 1。测试 TestExitOnErrorLogsWithoutStack(子进程重跑模式)断言含错误行、不含 goroutine、退出码 1。真实崩溃路径仍走各 handler 的 recovery.Exit() 保留堆栈。

@kooksee

kooksee commented Nov 3, 2026

Copy link
Copy Markdown
Contributor Author

追加提交 83e01f9 refactor(deps)!: remove write-only lockfile:经排查 protobuf.lock.yaml 属只写不读机制——resolution 从不消费 lock(loadLockfile 仅 verify 用于漂移警告),可重现性实际由 protobuf.yaml checksum(配置指纹)+ .proto/manifest.yaml(per-file sha256)两层承担。维护者决策砍掉该机制:删除 lockfile.go/writeLockfile/verify 漂移分支/TestLockfileDiff,本仓库 protobuf.lock.yaml 退库,README/AGENTS.md 表述同步为"依赖完整性:manifest+checksum"。外部项目残留的 lock 文件变成无引用文件,可随手删。verify 行为已复现验证:vendor 不再写 lock、verify 通过且无 lock 警告、manifest 校验层完好。

- grpc-gateway template: openapiv2 plugin sets skip_base (protoc-gen-openapiv2 has no paths/module flags; protoc failed atomically and blocked all gen outputs)

- verify: dep-less projects with empty vendor dir pass (empty set); stray vendor content without manifest still fails

- parseConfig: reset globalCfg before unmarshal so fields absent from the document cannot leak across in-process re-parses (doctor)

- commands.md: verify/init rows match shipped behavior
@kooksee

kooksee commented Nov 3, 2026

Copy link
Copy Markdown
Contributor Author

追加 init 默认体验重做(be4a135..7fc154e,设计与计划见 docs/superpowers/):

  • 三模板统一带 base:(basic/minimal=source_relative,gateway=import);module 仅在 import 模式填充——冒烟证实 protoc-gen-go 拒绝 module=+source_relative 组合,旧交互模式一直在产 gen 必挂的配置,本次一并治愈
  • 删 WKT github 依赖(protoc/buf/lint 引擎均内置解析,克隆整个 protocolbuffers 仓纯属浪费)
  • gateway 模板带精选 linter 规则块 + openapiv2 skip_base(评审发现:该插件无 paths/module flags,否则 gateway gen 原子失败)
  • createExampleProto 死代码接线:空 root 目录时生成示例 greeter.proto,init→vendor→gen 开箱全链路可用(basic 实测产出 .pb.go+.pb.gw 依赖的 grpc 包除外)
  • verify 对零依赖+空 vendor 按空集通过(评审发现:新默认零依赖,否则推荐 verify 作 CI 门禁的技能文档会让每个新项目永久红);散落文件无 manifest 仍失败
  • parseConfig 重置 globalCfg(同根因加固:doctor 进程内二次 parse 字段泄漏)
  • 技能文档(SKILL.md workflow①、commands.md init/verify 行、config.md WKT 注记、README 示例)同步;守卫测试与 shuffle×N 全绿

@kooksee
kooksee merged commit 78cc5b5 into main Nov 4, 2026
2 checks passed
@kooksee

kooksee commented Nov 4, 2026

Copy link
Copy Markdown
Contributor Author

Post-merge acceptance closed: npx skills add pubgo/protobuild real-install verified on default branch (2026-11-04). Installed to .agents/skills/protobuild/ — SKILL.md + agents/openai.yaml + references/{commands,config,troubleshooting}.md; diff -r against repo source of truth: identical. All 6 spec acceptance criteria and the deferred install proof are now closed.

@kooksee kooksee mentioned this pull request Nov 4, 2026
5 tasks done
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant