ACCEPTED

AIOS · Commit Message 规范 v1.0

关联:本文件是 ADR-AIOS-06 §2.5 的展开实施手册。配合 Process-Model.md(K/U 线程定义)+ Scheduling-Algorithm.md(RUNQ 派发)+ Concurrency-Domains.md(并发域)使用。

核心思想(议题 3 verbatim):

"commit message 不需要知道哪个智能体干了什么 · 只需要知道哪个进程的哪个线程完成了什么(类比'操作系统不需要知道哪个 CPU 核心做了什么')。"

1. 完整格式

1.1 标准模板

<type>(<pid>.U<N>/<thread-name>): <subject>

[step=<N>/<M>] [pid=<P>] [uid=U<N>] [occupies=K<a>+K<b>+...] [files=<f1>,<f2>,...]
[ipc=<channel>|none]

<body · 多行可选 · 描述具体改动 / 验收要点 / 关联 ADR>

<footer · 可选 · 包含 [need: ClaudeX] trailer / Refs / Closes>

1.2 字段对照表

位置	字段	必填	说明
Header	`<type>`	✅	conventional-commits 类型(feat/fix/chore/refactor/docs/test/...)
Header	`(<pid>.U<N>/<thread-name>)`	✅	scope · 严格对应 PCB 中的 user_thread
Header	`<subject>`	✅	50 字符内的祈使句概述
Body §1	`[step=N/M]`	✅	当前是 U-thread 的第几步(N)共几步(M)
Body §1	`[pid=P_x]`	✅	进程 ID(冗余于 scope · 便于 grep)
Body §1	`[uid=U_y]`	✅	用户线程 ID
Body §1	`[occupies=K_a+K_b+...]`	✅	占用的 K-thread 集合(用 `+` 连接)
Body §1	`[files=...]`	✅	本次实际修改的文件清单(逗号分隔)
Body §2	`[ipc=<ch>\\|none]`	✅	IPC 通道(无跨栈通信写 `none`)
Body §3+	自由文本	⚪	详细说明 / 验收要点
Footer	`[need: ClaudeX]`	⚪	跨智能体协作请求(走 AIOS 中转)
Footer	`Refs: ADR-AIOS-NN`	⚪	关联 ADR / Issue

1.3 实例(P3.U2 · ClaudeC 完成 step ⅔)

feat(P3.U2/tuning-mode-ui): readonly badge + auto_inverse overlay 落地

[step=2/3] [pid=P3] [uid=U2] [occupies=P3.K5+P3.K7+P0.K-shared-types]
[files=src/stages/xitune/TuningModeSwitcher.vue,src/stores/tuningModeStore.ts,src/types/tuningMode.ts]
[ipc=none]

- 在 TuningModeSwitcher 添加 readonly badge 视觉表达
- auto_inverse overlay 通过 store action 切换 · 不触发后端 IPC
- 类型扩展 tuningMode.ts:新增 TuningModeOverlay 联合类型

Refs: ADR-AIOS-05 · P3.U1 (88a7701)

2. type 词表(conventional-commits 子集)

type	用途	典型 PCB 操作
`feat`	新功能(主要业务任务)	U-thread 主体 step
`fix`	bug 修复	step 后期或 hotfix U-thread
`chore`	元数据 / 配置 / RUNQ 重算	AIOS 维护类 commit
`refactor`	重构(行为不变)	内部清理 · 不增加功能
`docs`	文档变更	P_arch / P0 文档调整
`test`	测试代码	P4 主战场 / 测试补充
`style`	代码风格(不影响逻辑)	罕见 · 通常并入 refactor
`perf`	性能优化	罕见 · 配 benchmark 数据
`build`	构建系统 / 依赖	P6.K5-build-system / package.json
`ci`	CI 配置	.github/workflows/*

v0.3 新增惯例: - 涉及 P_contracts 修改时强烈建议用 feat 或 docs · 不用 chore - RUNQ 重算用 chore(P_arch.ADR-06/runq-recompute) - ADR 起草用 docs(P_arch.ADR-NN/<topic>)

3. 三元组校验规则(`[pid=]` `[uid=]` `[occupies=]`)

3.1 三元组的内在一致性

header_scope:  (P3.U2/tuning-mode-ui)
                   │   │
                   │   └─ uid 必须 == [uid=U2]
                   └───── pid 必须 == [pid=P3]

PCB 真值源:    processes/P3-xitune/PROCESS.md
                   user_threads:
                     - uid: P3.U2
                       name: tuning-mode-ui  ← 与 header 的 thread-name 一致
                       occupies: [P3.K5, P3.K7, P0.K-shared-types]
                                              │
                       header [occupies=P3.K5+P3.K7+P0.K-shared-types]  ✅

3.2 校验项清单

校验项	规则	git hook 检查
三元组完整性	必含 `[pid=]` `[uid=]` `[occupies=]`	✅
pid 与 scope 一致	`(P3.U2/...)` 中的 P3 == `[pid=P3]`	✅
uid 与 scope 一致	`(P3.U2/...)` 中的 U2 == `[uid=U2]`	✅
thread-name 存在于 PCB	scope 中的 `tuning-mode-ui` 必须能在 PCB.user_threads.name 找到	✅
occupies 中每个 K 真实存在	每个 K_x 必须能在某进程的 PCB.kernel_threads 找到	✅
files ⊆ K.file_claims 并集	实际修改的文件必须 ⊆ occupies 所列 K 的 file_claims 并集	⚠️ 复杂 · v1.0 仅 warn
K 状态校验	occupies 中所有 K.state 应 == running	✅(查 RUNQ.md)
跨栈 IPC 必走 P_contracts	若 [ipc=...] 且涉及跨栈 · via 必含 P_contracts.K1	⚠️ v1.0 仅 warn

3.3 特殊场景

3.3.1 RUNQ 重算 / 元数据 commit

chore(P_arch.ADR-06/runq-recompute): standup 2026-05-26 RUNQ 重算

[step=1/1] [pid=P_arch] [uid=U-runq-recompute]
[occupies=none] [files=docs/08-implementation/40-aios/RUNQ.md]
[ipc=none]

[occupies=none] 表示该 U-thread 不占用任何 K-thread(纯元数据维护)。

3.3.2 hotfix(无对应 U-thread)

紧急 hotfix 允许临时绕过 PCB 注册,但 commit 必须显式标 [uid=U-hotfix-<timestamp>],事后 AIOS 在对应进程 PCB 补登 zombie 记录。

fix(P5.U-hotfix-20260526-1730/refresh-link-crash): 修复 WS 断线后内存泄漏

[step=1/1] [pid=P5] [uid=U-hotfix-20260526-1730]
[occupies=P5.K4+P5.K5] [files=WebSocket/Connection.cs,Routes/RefreshLink.cs]
[ipc=none]

紧急 hotfix · 走 ADR-AIOS-06 §3.3.2 例外通道 · AIOS 事后补登 PCB

4. git hook 校验脚本模板

4.1 `.git/hooks/commit-msg`(bash 实现)

#!/usr/bin/env bash
# AIOS Commit Convention Validator v1.0
# 触发:每次 git commit 时校验 message
# 7 天宽限期:2026-05-26 起 · 2026-06-02 起硬拒(改 GRACE_END 关闭)

set -e

GRACE_END="2026-06-02"
TODAY=$(date +%Y-%m-%d)
MSG_FILE="$1"
MSG=$(cat "$MSG_FILE")

# 决定 fail 还是 warn
fail() {
  if [ "$TODAY" \< "$GRACE_END" ]; then
    echo "⚠️  AIOS commit warning: $1"
    echo "    (宽限期 · 不阻断 commit · 2026-06-02 后将硬拒)"
    return 0
  else
    echo "❌ AIOS commit reject: $1"
    return 1
  fi
}

# §1 三元组完整性
if ! echo "$MSG" | grep -qE '^\[step=[0-9]+/[0-9]+\]'; then
  fail "缺 [step=N/M]" || exit 1
fi
if ! echo "$MSG" | grep -qE '\[pid=[A-Za-z_0-9]+\]'; then
  fail "缺 [pid=...]" || exit 1
fi
if ! echo "$MSG" | grep -qE '\[uid=U[-A-Za-z_0-9]+\]'; then
  fail "缺 [uid=U...]" || exit 1
fi
if ! echo "$MSG" | grep -qE '\[occupies=([A-Za-z_0-9.+-]+|none)\]'; then
  fail "缺 [occupies=K_a+K_b+...] 或 [occupies=none]" || exit 1
fi
if ! echo "$MSG" | grep -qE '\[ipc=[^]]+\]'; then
  fail "缺 [ipc=<channel>|none]" || exit 1
fi

# §2 header scope 与 [pid] [uid] 一致
HEADER=$(echo "$MSG" | head -n1)
SCOPE_PID=$(echo "$HEADER" | sed -nE 's/^[a-z]+\(([A-Za-z_0-9]+)\..*$/\1/p')
SCOPE_UID=$(echo "$HEADER" | sed -nE 's/^[a-z]+\([A-Za-z_0-9]+\.U([-A-Za-z_0-9]+)\/.*$/U\1/p')
BODY_PID=$(echo "$MSG" | grep -oE '\[pid=[A-Za-z_0-9]+\]' | sed 's/\[pid=//;s/\]//')
BODY_UID=$(echo "$MSG" | grep -oE '\[uid=U[-A-Za-z_0-9]+\]' | sed 's/\[uid=//;s/\]//')

if [ -n "$SCOPE_PID" ] && [ "$SCOPE_PID" != "$BODY_PID" ]; then
  fail "scope pid ($SCOPE_PID) 与 [pid=$BODY_PID] 不一致" || exit 1
fi
if [ -n "$SCOPE_UID" ] && [ "$SCOPE_UID" != "$BODY_UID" ]; then
  fail "scope uid ($SCOPE_UID) 与 [uid=$BODY_UID] 不一致" || exit 1
fi

echo "✅ AIOS commit convention OK"
exit 0

4.2 `.git/hooks/commit-msg.ps1`(PowerShell 实现 · Windows 主用)

沿用 .clinerules/aios-orchestration.md PowerShell 实战经验: - 必须落到 .ps1 文件用 powershell -NoProfile -File 调用 - 禁止 pwsh -c "..." - .ps1 含中文必须保存为 UTF-8 with BOM(PS 5.1 否则按 GBK 解析报错)

# .git/hooks/commit-msg.ps1
# AIOS Commit Convention Validator v1.0(PowerShell 5.1+ 兼容)
$ErrorActionPreference = 'Stop'

$graceEnd = Get-Date '2026-06-02'
$today = Get-Date

$msgFile = $args[0]
$msg = Get-Content -Path $msgFile -Raw -Encoding UTF8

function Invoke-AiosCheck($pattern, $errorHint) {
  if ($msg -notmatch $pattern) {
    if ($today -lt $graceEnd) {
      Write-Warning "⚠️  AIOS commit warning: $errorHint(宽限期 · 不阻断 · 2026-06-02 后硬拒)"
      return $true
    } else {
      Write-Error "❌ AIOS commit reject: $errorHint"
      return $false
    }
  }
  return $true
}

$ok = $true
$ok = $ok -and (Invoke-AiosCheck '\[step=\d+/\d+\]' '缺 [step=N/M]')
$ok = $ok -and (Invoke-AiosCheck '\[pid=[\w]+\]' '缺 [pid=...]')
$ok = $ok -and (Invoke-AiosCheck '\[uid=U[-\w]+\]' '缺 [uid=U...]')
$ok = $ok -and (Invoke-AiosCheck '\[occupies=([\w.+-]+|none)\]' '缺 [occupies=K_a+K_b+...] 或 [occupies=none]')
$ok = $ok -and (Invoke-AiosCheck '\[ipc=[^\]]+\]' '缺 [ipc=<channel>|none]')

if ($ok) {
  Write-Host '✅ AIOS commit convention OK'
  exit 0
} else {
  exit 1
}

.git/hooks/commit-msg(无扩展名 · bash wrapper):

#!/usr/bin/env bash
exec powershell -NoProfile -ExecutionPolicy Bypass -File "$(dirname "$0")/commit-msg.ps1" "$@"

4.3 安装方式(项目级)

把上述 hook 文件提交到 scripts/git-hooks/ · 项目根目录加 .gitconfig 或在 README 中说明:

# 一次性安装(开发者本地)
cp scripts/git-hooks/commit-msg .git/hooks/commit-msg
cp scripts/git-hooks/commit-msg.ps1 .git/hooks/commit-msg.ps1
chmod +x .git/hooks/commit-msg .git/hooks/commit-msg.ps1

或用 core.hooksPath:

git config core.hooksPath scripts/git-hooks

5. occupies 语法详解

5.1 基本语法

[occupies=<K_atom>(+<K_atom>)*]
[occupies=none]

<K_atom> 形如 P3.K5 / P_contracts.K1 / P0.K-shared-types
多个用 + 连接(不用空格 · 不用逗号)
单纯元数据 commit 用 [occupies=none]

5.2 K-atom 命名约束

模式	例	说明
`P<N>.K<M>`	`P3.K5`	编号型 · N=进程序号 · M=K-thread 序号
`P_<name>.K<M>`	`P_contracts.K1`	arch / 系统进程 · M=K-thread 序号
`P0.K-<name>`	`P0.K-shared-types`	P0 共享栈特例 · 不走数字编号

5.3 跨进程 K 引用规则

[occupies=P3.K5+P3.K7+P0.K-shared-types+P_contracts.K1]
                            │                  │
                            │                  └─ 跨栈契约引用(读)
                            └─ P0 daemon 共享栈(写)

v0.3 强制: - 跨栈引用(P1-P4 → P5-P7)必须含 P_contracts.K1 - 修改 types/ 必须含 P0.K-shared-types - 修改 contracts/ 必须含 P_contracts.K1 且 author 是 ClaudeB

6. 全栈跨栈 commit 示例(v0.3)

6.1 ClaudeB 修改 protocol-v1(占 P_contracts.K1)

feat(P_contracts.U-protocol-v1-§4-§6/refresh-link-spec): 补全 §4-§6 双语义协议

[step=1/3] [pid=P_contracts] [uid=U-protocol-v1-§4-§6]
[occupies=P_contracts.K1] [files=contracts/protocol-v1.md]
[ipc=none]

- §4 增加 sourceList 数据结构定义
- §5 refresh-link 双语义(主动/被动)消息流程图
- §6 错误码表

Refs: ADR-AIOS-05 · ADR-AIOS-06 v0.3

6.2 ClaudeA 改 P3 但引用契约(P_contracts.K1 read-only)

feat(P3.U-call-refresh-link/integrate-protocol-v1): P3 集成 refresh-link 调用

[step=1/2] [pid=P3] [uid=U-call-refresh-link]
[occupies=P3.K7+P_contracts.K1+P0.K-shared-types]
[files=src/stores/linkStore.ts,src/types/refresh-link.ts]
[ipc=P_contracts.K1-protocol-v1.§5]

- 按 protocol-v1 §5 调用 refresh-link
- 新增 RefreshLinkMessage 类型(扩展 P0.K-shared-types)
- linkStore 双状态结合 (ADR-05)

注:本 commit 写 types/refresh-link.ts(read-write 占 P0.K-shared-types)
    读 contracts/protocol-v1.md(read-only 占 P_contracts.K1)
    实际不修改 protocol-v1.md · 但仍占 K1 防止与 ClaudeB B1-B4 冲突

Refs: ADR-AIOS-05 §5 / ADR-AIOS-06 v0.3 §6.1

6.3 ClaudeB 后端实现(P5)

feat(P5.U-refresh-link/finalize-ws-route): WS Route 落地 refresh-link 双语义

[step=3/3] [pid=P5] [uid=U-refresh-link]
[occupies=P5.K4+P5.K5+P_contracts.K1]
[files=Routes/RefreshLink.cs,WebSocket/MessageDispatcher.cs]
[ipc=P_contracts.K1-protocol-v1.§5]

- 实现 protocol-v1 §5 refresh-link 主动/被动消息双语义
- WS 路由注册 + dispatcher 分发
- 单元测试覆盖 4 种场景(主动 ack / 被动 push / 错误 / 超时)

Refs: ADR-AIOS-05 / ADR-AIOS-06 v0.3 / P_contracts.U-protocol-v1-§4-§6 (B2 zombie)

7.1 跨智能体协作 trailer(`[need: ClaudeX]`)

来自 ADR-AIOS-01 v3:跨智能体不直接对话 · 通过 AIOS 中转。

格式:

[need: ClaudeB] 需要后端在 P5.K1-controllers 加 /api/refresh-link POST endpoint
[need: ClaudeC] 需要前端在 P3.U-test-fix 验证 tuning-mode-ui 测试是否过

AIOS 在下次 standup 抓取时检测 trailer · 自动: 1. 在目标进程下 fork 新 U-thread(state: ready) 2. 添加到 RUNQ.md §需要你拍板的事项 3. 派发提示词文件给目标 CPU

7.2 关联引用

Refs: ADR-AIOS-NN · 其他 commit hash · Issue #NN
Closes: U-thread uid · Issue #NN(U-thread 完成时用)

8. 7 天宽限期与硬拒策略

8.1 时间线

日期	状态	行为
2026-05-26	v0.3 accepted · 规范生效	git hook 仅 warn · 不阻断 commit
2026-05-27 ~ 2026-06-02	7 天宽限期	warn 模式 · 旧格式 commit 允许
2026-06-02 EOD	宽限期结束	hook 改硬拒模式 · 不符规范的 commit 被拒

8.2 渐进式启用

宽限期内允许的"过渡格式": - 没有 [occupies=](默认视为 [occupies=none] · warn) - header 没有 scope(老 conventional commits · warn) - 任意 type 不在词表(允许 · warn 提示词表)

宽限期后硬拒的: - 缺 [pid=] 或 [uid=](三元组核心) - scope 与 [pid][uid] 不一致 - pid 在 PCB 中不存在

9. 常见问题 FAQ

Q1:一个 commit 横跨多个 U-thread 怎么办?

A:禁止。AIOS v7 的"任务原子性"原则要求一 commit ↔ 一 U-thread 的一 step。如果改动确实跨多 U,应: - 用 git add -p 拆成多次 commit - 或新建一个"复合 U-thread"统一 occupies

Q2:U-thread 内的多 step 是 commit 还是 push?

A:每个 step 独立 commit · 但可以打包一次 push。例:

cca9dee feat(P3.U2/tuning-mode-ui): step 1/3
2288c5e feat(P3.U2/tuning-mode-ui): step 2/3
a877d6f fix(P3.U2/tuning-mode-ui): step 3/3

完成 step 3/3 后整个 U-thread 状态变 zombie · AIOS 触发归档。

Q3:并发域 B(worktree)的 commit 是否走相同规范?

A:✅ 必须。Cline-Worker / Copilot-Worker / Continue-Worker 的所有 commit 都遵循本规范。merge 到 xistudio 时若有冲突,AIOS 主导 merge 时机(沿用 ADR-AIOS-06 §2.2 协议)。

Q4:旧 KANBAN 时代的 commit 历史怎么办?

A:不重写历史。KANBAN-archive-v6.md 保留旧记录 · 新 commit 起用新规范即可。git log 时旧 commit 缺 [pid=] 是正常的。

Q5:Cline-AIOS 的 commit 怎么写?

A:Cline-AIOS 仅在 06_docs/site-build/ 工作 · 几乎所有 commit 都属于 P_arch 进程:

docs(P_arch.ADR-06/write-process-model): 起草 agents/Process-Model.md v1.0

[step=1/1] [pid=P_arch] [uid=U2-write-process-model]
[occupies=none] [files=docs/08-implementation/40-aios/agents/Process-Model.md]
[ipc=none]

P_arch 没有 K-thread 所以 [occupies=none]。

10. 验收清单

任何 commit 完成后需通过以下校验:

header 含 type + scope (<pid>.U<N>/<thread-name>) + subject
body §1 五元组齐全:[step=] [pid=] [uid=] [occupies=] [files=]
body §2 含 [ipc=]
scope 中的 pid/uid 与 [pid=][uid=] 一致
thread-name 能在 PCB.user_threads.name 找到
occupies 中每个 K 都能在某进程的 PCB.kernel_threads 找到
涉及跨栈时 [ipc=] 含 P_contracts.K1
修改 types/* 时 [occupies=] 含 P0.K-shared-types
修改 contracts/* 时 [occupies=] 含 P_contracts.K1 且 author 是 ClaudeB

11. 文档元信息

创建:2026-05-26 17:20 · Step B · T4(ADR-AIOS-06 v0.3 实施)
版本:v1.0
同栈姊妹文档:Process-Model.md / Scheduling-Algorithm.md / Concurrency-Domains.md
git hook 模板:scripts/git-hooks/commit-msg + commit-msg.ps1(待 T6 落地)