📊 agentprof 可视化指南 · 目录 Wiki 14 / 14
Wiki

贡献指南

给 agentprof 提 PR 不是「随便写写然后 push」—— 整个流程被钉成一个 9 阶段 pipeline（详见 .github/copilot-instructions.md §5）：从 brainstorming 起步、写 spec、必要时写 ADR、写 plan、TDD 实现、本地 gate 验证、PR 审、合并。每个 stage 有专门 skill 支撑（meta、TDD、ADR、release 等）。Commit message 走 Conventional Commits，CHANGELOG 走 Keep a Changelog，SemVer 严格执行。

  1. Stage 0 — Boot
    using-superpowers / 项目规约加载
  2. Stage 1 — Discovery
    brainstorming → design.md
  3. Stage 2 — Decision
    create-architectural-decision-record (按需)
  4. Stage 3 — Planning
    writing-plans → plan.md
  5. Stage 4 — Implementation
    TDD：failing test → 实现 → green
  6. Stage 5 — CI / Infra
    横切层：改 workflow 时触发
  7. Stage 6 — Debugging
    横切层：fail 时返回原 stage
  8. Stage 7 — Completion
    verification-before-completion + review
  9. Stage 8 — Release
    github-release: tag + CHANGELOG + GH Release
🐧 类比 — 像 Linux kernel 的 patch flow
  • kernel：RFC patch → mailing list 讨论 → maintainer review → Tested-by / Acked-by → 进 -next → mainline merge。
  • agentprof：design spec → 用户 approve → 必要时 ADR → plan → 多 commit 实现（每 commit 自带 test + docs）→ verification-before-completion → PR → review → merge。
  • 共同点：先写清楚再写代码；任何「为什么这么做」的决策都有文档化痕迹；commit 粒度小、message 严谨；CI 是「最后一道门」而不是「我才发现 bug 的地方」。

agentprof 不是 kernel 那种「百人协作 + 数十 maintainer 同步」的规模，所以 pipeline 比 kernel 轻 —— 没有强制 mailing list、没有 Tested-by 标签 —— 但「先 design 再写、文档随代码合并」这两条核心同款。

9 阶段 pipeline 主线（主 stage 表）

Stage主产物谁负责 / 触发
0 Boot加载常驻 instructions（rust.instructions.md + update-docs-on-code-change.instructions.md）AI assistant 每次会话开头，invoke using-superpowers
1 Discovery / Designdocs/superpowers/specs/YYYY-MM-DD-<topic>-design.mdcontributor + user 走 brainstorming skill；user approve design 才进 stage 2
2 Decision Records（条件，见 §5.5）docs/internals/adr-NNNN-<topic>.mdcontributor 走 create-architectural-decision-record；门槛：≥2 候选方案 / 新公开 API / 否决既有 ADR / 事后补 hotfix ADR
3 Planningdocs/superpowers/specs/YYYY-MM-DD-<topic>-plan.mdcontributor 走 writing-plans；user approve plan 才进 stage 4
4 Implementation代码 + L3 rustdoc + 测试（每 commit 自带）contributor + subagents 走 test-driven-development；多 commit 也行，每 commit 满足「code + docs + tests 同 commit」
5 CI / Infra（横切）.github/workflows/*.yml + docs/internals/ci-<workflow>.md仅当本次 PR 改 workflow时触发；走 create-github-action-workflow-specification
6 Debugging（横切，回原 stage）失败测试 + 修复 commit（fix: 前缀）任意 stage 撞 bug → systematic-debugging → 修完返回原 stage
7 Completion verification本地 gate 输出证据 + PR description + CHANGELOG entrycontributor 走 verification-before-completion；CI 全绿 + reviewer approve 才能 merge
8 Release（仅 release 任务）CHANGELOG.md + SemVer tag + GitHub Release (cargo-dist 多平台 binary)走 github-release；commit 类型决定 SemVer bump（feat=minor / fix=patch / BREAKING=major）

⚠️ Recon 校正：「9 阶段」字面是 Stage 0..8，但 Stage 5 和 6 是横切层—— 不在主线上。主线只走 0 → 1 → 2 → 3 → 4 → 7 → 8。仅两种快通道允许越级：trivial 改动（typo / 注释 / lint fix）跳过 Stage 1-3；hotfix 走 0 → 6 → 7 → 8 然后事后补 Stage 2 ADR。详见 .github/copilot-instructions.md §5.3 / §5.5 / §5.6。

👇 三张卡片：① Conventional Commits 全部 type 列表（本仓库已全用过）· ② 9 阶段 pipeline brief（recon §5 真实命名）· ③ 实操 4 步：开 PR / 加 ADR / 通过 CI / 写 CHANGELOG。

1 Conventional Commits 全部 type（本仓库已用全集） 点击展开
📝 全部 type（按本仓库 git log 频率排序）
type 什么时候用 SemVer 影响
feat:新功能、新 cli 子命令、新 adapter、新 feature flagminor bump
fix:bug 修复（必须配回归测试）patch bump
docs:改 README / docs/ / rustdoc，不动代码逻辑无（不发版）
test:加 / 改测试，不动产品代码无
refactor:重构（不变外部行为），改完 test 全绿无（除非破坏 pub API）
chore:杂项：bump 依赖、调 Cargo.toml metadata、release commit无（chore(release) 触发 tag）
build:改构建系统：xtask、cargo-dist、Cargo workspace 结构无
ci:改 .github/workflows/*.yml（同时触发 Stage 5）无
BREAKING:
or feat!: / fix!:		破坏 pub API / wire format / CLI 协议major bump（pre-1.0 也可以走 minor）

scope 写不写：optional，加了能锁定子系统 —— feat(adapters): add gemini adapter 比 feat: add gemini adapter 更易扫读。常用 scope：core / adapters / storage / tui / cli / xtask。

✍️ commit message body 怎么写
第一行：type(scope): 一句话主谓宾，≤72 字符。空一行。body：解释「为什么」（不是「做了什么」—— diff 自己看就行）；列关键决策、trade-off、为什么选这个不选那个。footer：Refs: #N / Closes: #N / BREAKING CHANGE: ... / Co-authored-by: ...。本仓库强制：AI assistant 写的 commit 必带 Co-authored-by: Copilot <...>。
2 9 阶段 pipeline brief（主线 + 横切层 + ADR 门槛） 点击展开
🔄 主线 7 stage 工作流（recon §5.1 真实命名）
Stage 0 [Boot]
  - 加载 .github/instructions/*.instructions.md（rust + update-docs）
  - skill: using-superpowers（meta）

Stage 1 [Discovery / Design]
  - 触发：新 feature / 新 adapter / 架构变更
  - skill: brainstorming
  - 产物：docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
  - 出口：user approve design

Stage 2 [Decision Records]（条件触发，§5.5 门槛）
  - skill: create-architectural-decision-record
  - 产物：docs/internals/adr-NNNN-<topic>.md
  - 编号 NNNN 单调递增（冲突取已合并 max+1）

Stage 3 [Planning]
  - skill: writing-plans
  - 产物：docs/superpowers/specs/YYYY-MM-DD-<topic>-plan.md
  - 出口：user approve plan

Stage 4 [Implementation]
  - skill: test-driven-development（必）
  - 辅: executing-plans / subagent-driven-development /
        dispatching-parallel-agents / cli-mastery / copilot-cli-quickstart
  - 产物：代码 + L3 rustdoc + 测试（每 commit 自带）
  - 任意 bug → Stage 6（横切，修完回 Stage 4）
  - 改 workflow → Stage 5（横切，不阻塞主线）

Stage 7 [Completion verification]
  - skill: verification-before-completion（必）
  - 跑全部本地 gate（cargo fmt + clippy + test + doc）
  - 附输出证据到 PR description；写 CHANGELOG entry

Stage 8 [Release]（仅 release 任务）
  - skill: github-release
  - SemVer 决策（按 commit type 推 bump）+ Keep-a-Changelog + tag + GH Release
🔀 横切层 5 / 6
Stage 5 CI/Infra：仅当 PR 改 .github/workflows/*.yml 时触发。和主线并行，不阻塞 Stage 4 / 7。skill：create-github-action-workflow-specification，产物含 spec md。Stage 6 Debugging：任意 stage 撞 bug / test 失败 / CI 红就进 → systematic-debugging 写复现 + 根因 + 修复 → 修完返回触发它的 stage（不前进）。修复 commit 用 fix: 前缀，关联失败测试。
📜 Stage 2 ADR 触发门槛（§5.5）
必写 ADR：① design 含 ≥2 个被认真考虑的方案；② 引入新 crate / 新 trait / 新公开 API 的关键设计；③ 否决 / 修改既有 ADR（旧的加 Status: Superseded by adr-MMMM）；④ hotfix（即使越级 Stage 1，也事后补 ADR）。SKIP：① 显然方案无替代；② typo / README / lint fix；③ doctest 示例改；④ workspace 内部重构不变 pub API。口诀：「半年后回头看这次改动会问『为什么这么做』，就写 ADR」。
3 实操 4 步：开 PR / 加 ADR / 通过 CI / 写 CHANGELOG 点击展开
📋 步骤 1：开 PR 前本地 gate（必跑）
# 格式 + lint
cargo fmt --all
cargo clippy --workspace --all-targets --all-features -- -D warnings

# 测试
cargo test --workspace --all-features
cargo insta test --check                  # snapshot 校验

# 文档（必须无 warning）
RUSTDOCFLAGS="-Dwarnings" cargo doc --no-deps --workspace --all-features

# 依赖审计（如改了 dep）
cargo deny check

全绿才能开 PR。CI 会跑同样的 gate；本地先跑省 PR 红/绿来回。

📋 步骤 2：加 ADR（如触发 §5.5）
  1. 查最大编号：ls docs/internals/adr-*.md | sort | tail -1 → 取 max+1。
  2. 创建文件：docs/internals/adr-NNNN-<topic>.md。
  3. 必备段落：Status（Accepted / Proposed / Superseded）、Date、Deciders、Related（链到上游 ADR）、Context、Decision、Consequences、Considered alternatives（每个有 rationale 说明为啥被否）。
  4. commit 单独成一条：docs(adr): NNNN <short title>。
  5. 同步更新 docs/internals/index.md（如有）+ 引用它的代码顶部 //!。
📋 步骤 3：通过 CI
CI workflow（.github/workflows/ci.yml）跑：cargo fmt --check · cargo clippy -D warnings · cargo test --all-features · cargo deny check · RUSTDOCFLAGS="-Dwarnings" cargo doc --no-deps · docs-sync（验证 pub API 改动配 rustdoc / README 改动）。red CI 的常见原因：① 公开 API 没加 # Examples（missing_docs = error）；② 改了某 crate 没改对应 README.md（docs-sync fail）；③ 用了 unwrap()（clippy unwrap_used = deny）；④ lib crate 用了 anyhow（只允许 bin 用）。修完force-push 没问题 —— 本仓库没强制 linear history。
📋 步骤 4：写 CHANGELOG entry
CHANGELOG.md 走 Keep a Changelog 格式：

## [Unreleased]

### Added
- xtask: visual-guide subcommand generates 14-lesson HTML site (T18).

### Changed
- ...

### Fixed
- ...

### Deprecated / Removed / Security
- ...

规则：① 每个 PR 至少加一行（小 typo 例外）；② release 时 github-release skill 把 [Unreleased] 整段挪到 [v0.X.Y] — YYYY-MM-DD；③ 用用户语言写（「now supports OTLP HTTP receiver」> 「added serve_http fn」）；④ 链 issue/PR：(#42)。

🆘 还有问题
读完整指南：CONTRIBUTING.md（顶级规则）+ .github/copilot-instructions.md（AI assistant 详尽版，也适合人读）。仍有疑问，开 GitHub Discussion，maintainer 会引导你走对应 stage 的 skill。

本套指南到此完结

这是 agentprof 可视化指南的最后一课 —— 用法 6 课带你从安装到 dashboard、Wiki 8 课带你从架构到贡献。如果你跟着读到了这里：感谢你的耐心，欢迎来 GitHub verdenmax/agentprof 提 issue / PR / Discussion。

📂 相关源码：CONTRIBUTING.md  顶级贡献规则

📂 相关源码：.github/copilot-instructions.md  AI / 人共用的详尽 pipeline 文档

📂 相关源码：CHANGELOG.md  Keep-a-Changelog 历史