ACCEPTED

AIOS · 进程模型与 PCB 规范 v1.0

关联:本文件是 ADR-AIOS-06 v0.3 决议的展开实施手册。 ADR-06 定义"为什么这么做" · 本文件定义"具体怎么写 PROCESS.md / kernel_threads/THREAD.md / user_threads/STEP.md"。

同栈姊妹文档: - Scheduling-Algorithm.md — RUNQ 6 步调度算法 - Commit-Convention.md — commit message [pid=][uid=][occupies=] 规范 - Concurrency-Domains.md — 二层并发域(A 文件级 / B 分支级)+ 主战场配置

1. 三层解耦速查

Layer 3 · 任务层(Process / Thread · 与 CPU 无关 · 不含 owner 字段)
        ↑ U-thread 入就绪队列 RUNQ
Layer 2 · 调度层(AIOS 内核 · K-thread 校验 + 优先级 + 缓存亲和)
        ↓ 派发(动态绑定)
Layer 1 · 执行层(CPU 池 · 并发域 A claude code 4 兄弟 + 并发域 B worktree 三兄弟)

铁律: 1. Process / Thread 描述符不含 owner 字段 — 谁来跑都行 2. K-thread 不进 RUNQ(基础设施 · 永远存在) 3. 只有 U-thread 进 RUNQ 接受调度

2. 进程分类(Process Type)

2.1 三种进程类型

类型	状态特征	生命周期	v0.3 全栈 10 进程成员
daemon · 守护进程	永不 zombie · 系统启动即创建	与项目同生死	P0 XiShell · P5 backend-csharp · P6 dsp-algo · P7 pysidecar · P_contracts
user-process · 业务进程	整体常驻 · 内部 thread 频繁 fork-zombie	与对应 stage 同生命周期	P1 XiLink / P2 XiForge / P3 XiTune / P4 XiTest
arch-event · 架构事件进程	完成即整体 zombie · 不再唤醒	与 ADR 同生命周期	P_arch/ADR-04 / ADR-05 / ADR-06 / ...

2.2 状态机

进程整体状态(PROCESS.md state 字段):
  ready    ←  刚创建 · 等所有依赖就位
  running  ←  至少一个 U-thread 在跑
  blocked  ←  全部 U-thread blocked(罕见 · 通常出现在等契约 freeze)
  zombie   ←  仅 arch-event 类型 · 完成后归档

daemon 进程永远不会进 zombie,即使 user_threads 全部 zombie · 只是整体 state=running 内部 K-thread 全 sleeping。

3. 线程分类(Thread Type · 模型核心)

3.1 K-thread vs U-thread 对比

维度	K-thread(内核/常驻线程)	U-thread(用户/临时线程)
本质	模块所有权登记(file_claims 范围声明)	临时业务任务(完成即归档)
生命周期	与父进程同生死 · 不会 zombie	完成即 zombie · 归 archive/
状态机	`sleeping`(无 U 占用)/ `running`(被 U 占用)/ `extending`(架构升级中)	`ready` / `running` / `blocked` / `zombie`
进 RUNQ	❌ 不进(基础设施)	✅ 进 RUNQ 等调度
OS 类比	内核数据结构(VFS / 设备驱动)	进程开的文件描述符
存放位置	`processes/<pid>/kernel_threads/K<N>-<name>/THREAD.md`	`processes/<pid>/user_threads/U<N>-<name>/STEP-*.md`

3.2 K-thread / U-thread 的耦合关系

U-thread 修改的文件 ⊆ U.occupies 列表中所有 K-thread.file_claims 的并集
  ↓
K-thread 是文件所有权的登记中心(永远存在)
U-thread 是临时占用 K-thread 来干活的执行单元(完成走人)
  ↓
两者通过 occupies 字段的"file_claims 子集匹配"建立隶属关系

派发的核心校验(详见 Scheduling-Algorithm.md): - U-thread 入 RUNQ 时声明 occupies: [K_a, K_b, ...] - 派发前 AIOS 校验所有 K_x.state 必须是 sleeping - 派发执行 → U.state=running · 同时所有 K_x.state=sleeping→running - U commit 完成 → U.state=zombie · 所有 K_x.state=running→sleeping(释放)

3.3 K-thread 的"模块所有权"语义

K-thread 不是任务 · 是永久的文件所有权登记表。例:

# processes/P3-xitune/kernel_threads/K7-stores/THREAD.md
kid: P3.K7
name: stores
type: kernel-thread
state: sleeping   # 当前没 U-thread 占用
file_claims:
  - stores/presetStore.ts
  - stores/profileStore.ts
  - stores/tuningModeStore.ts
  - stores/linkStore.ts    # 注:与 P1.K7 共享读 · 但 P3 只读引用 · 不写
description: |
  XiTune 业务 stores 集合 · 含 linkStore 双状态(ADR-05)。
  任何修改 stores/*.ts 的 U-thread 必须在 occupies 中声明 P3.K7。
last_modified_by: P3.U3 (zombie · 2026-05-26 15:00 · commit edd75d7)

关键: 1. last_modified_by 字段记录最近一次释放它的 U-thread · 用于缓存亲和性算法 2. K-thread 没有 owner · 任何 CPU 都可以通过 U-thread 占用它 3. K-thread 之间可能存在file_claims 重叠(如 linkStore.ts 同时被 P1.K7 和 P3.K7 声明) → 必须在 THREAD.md 中标注"读"还是"写"权限

3.4 跨进程 K-thread 引用(共享栈)

P0 daemon 持有的三个 K-shared- 是全局共享栈*:

# processes/P0-xishell/kernel_threads/K-shared-types/THREAD.md
kid: P0.K-shared-types
name: shared-types
type: kernel-thread
state: sleeping
file_claims:
  - types/**/*.ts
description: |
  全局类型定义 · 所有进程可读 · 写需通过 occupies 声明。
  典型占用者:P3.U2 (tuningMode.ts) · P2.U5 (widget.ts uid namespace)

任何业务进程需要修改 types/ 下的文件,U-thread 的 occupies 必须包含 P0.K-shared-types,例:

# processes/P3-xitune/user_threads/U2-tuning-mode-ui/STEP.md(片段)
uid: P3.U2
occupies:
  - P3.K5             # 自身 stage-toolbar
  - P3.K7             # 自身 stores
  - P0.K-shared-types # 跨进程 · 因为改 types/tuningMode.ts

4. PCB(进程控制块)YAML Schema

每个进程根目录下的 PROCESS.md 是该进程的 PCB,使用 frontmatter YAML + Markdown body 双段式。

4.1 完整 schema

---
# 必填字段
pid: P3                       # 进程 ID(P0-P7 / P_contracts / P_arch)
name: xitune                  # 进程短名(英文 kebab-case)
type: user-process            # daemon / user-process / arch-event
state: running                # ready / running / blocked / zombie
priority: P0                  # P-1(超紧急) / P0 / P1 / P2

# 关联字段
parent: null                  # arch-event 进程才有 parent(指向触发 ADR)
created: 2026-05-19           # 创建日期
last_modified: 2026-05-26     # 最近一次 PCB 修改日期

# K-thread 列表(基础设施 · 不进 RUNQ)
kernel_threads:
  - kid: P3.K1
    name: page-layout
    state: sleeping
    file_claims: [stages/xitune/index.vue]
    description: 主页面布局 · 16 TuningDialog 容器
  # ... K2 ~ Kn

# U-thread 列表(临时业务 · 进 RUNQ)
user_threads:
  - uid: P3.U1
    name: tuning-mode-system
    state: zombie
    completed_at: 2026-05-26 12:25
    last_commit: 88a7701
    occupies: [P3.K7]
  # ... U2 ~ Un

# 共享资源声明(跨进程引用 · 非独占)
shared_resources:
  - via: P0.K-shared-types
    files: [types/tuningMode.ts, types/xmlTuning.ts]
  - via: P1.K7
    files: [stores/linkStore.ts]
    access: read-only          # 必须明示 read-only / read-write

# IPC 通道(进程间通信 · v0.3 强制走 P_contracts)
ipc_channels:
  - to: P5-backend-csharp      # 目标进程
    via: P_contracts.K1-protocol-v1   # 必须走系统调用表
    purpose: refresh-link 双语义协议
  - from: P_arch/ADR-AIOS-05   # 来自架构事件
    via: arch-event
    purpose: workspace 接收 ADR-05 决议派发
---

## 进程描述

(Markdown body · 写进程的业务定位 / 历史背景 / 关键里程碑 / 已知阻塞 / 与其他进程关系)

4.2 K-thread / U-thread 状态字段细化

K-thread 状态机:

state	含义	触发转移
`sleeping`	默认状态 · 无 U-thread 占用	释放(U.state→zombie)
`running`	至少一个 U-thread 占用中	派发(U.state→running 时同步)
`extending`	架构升级中(ADR 决议变更 file_claims)	ADR 触发 · 完成后回 sleeping

U-thread 状态机:

state	含义	触发转移
`ready`	已声明 · 等 RUNQ 派发	创建 / 解除 blocked
`running`	已派发 · CPU 在执行	RUNQ 派发(K 校验通过)
`blocked`	等其他 U-thread 完成 / 等契约 freeze	显式声明 blocked_on 字段
`zombie`	完成 · 等归档	完成 commit 后由 AIOS 移到 archive/

U-thread 必填字段(进 RUNQ 必备):

- uid: P3.U2                  # P{n}.U{m} 格式
  name: tuning-mode-ui        # kebab-case
  state: ready                # 入 RUNQ 时必须是 ready
  priority: P0                # 可省略 · 默认继承父进程 priority
  occupies:                   # K-thread 占用清单(可跨进程)
    - P3.K5
    - P3.K7
    - P0.K-shared-types
  blocked_on: null            # 阻塞的其他 U-thread uid(若 state=blocked)
  eta: 2026-05-27             # 预期完成日期(可选)
  hard_deadline: false        # 是否硬截止(true 时优先级 +1)
  completed_at: null          # 完成时间戳(state=zombie 时填)
  last_commit: null           # 完成 commit hash(state=zombie 时填)

5. v0.3 全栈 10 进程拓扑映射

5.1 进程清单

PID	名称	类型	K-thread 数	主战场 CPU	关联模块(04_development)
P0	xishell	daemon	9(K1-K6 + K-shared-types/contracts/test-aux)	ClaudeA	`frontend_vue3/src/components/shell/` + `shared/`
P1	xilink	user-process	7(K1-K7)	ClaudeA	`frontend_vue3/src/stages/xilink/`
P2	xiforge	user-process	7(K1-K7)	ClaudeA	`frontend_vue3/src/stages/xiforge/`
P3	xitune	user-process	7(K1-K7)	ClaudeA	`frontend_vue3/src/stages/xitune/`
P4	xitest	user-process	6(K1-K6)	ClaudeA / ClaudeD	`frontend_vue3/src/stages/xitest/`
P5	backend-csharp	daemon	9(K1-K9)	ClaudeB	`backend_csharp/{Controllers,Services,Models,WebSocket,Routes,Interop,AIAgent,Extensions,data}`
P6	dsp-algo	daemon	6(K1-K6)	ClaudeB	`dsp_algo/{framework,modules,platform,include,make,build,config}`
P7	pysidecar	daemon	3(K1-K3)	ClaudeB(兼管)	`pysidecar/{analyzer,reporter,scripts}`
P_contracts	contracts	daemon	1(K1-protocol-v1)	ClaudeB(写权限独占)	`contracts/protocol-v1.md`
P_arch	arch-events	arch-event 容器	0(只 user_threads)	Cline-AIOS	(元层 · 06_docs/site-build)

5.2 P5-backend-csharp 详细 K-thread 列表(v0.3 新增)

# processes/P5-backend-csharp/PROCESS.md(K-thread 段)
kernel_threads:
  - kid: P5.K1
    name: controllers
    file_claims: [Controllers/**]
    description: MVC 路由层(ASP.NET Core Controllers)
  - kid: P5.K2
    name: services
    file_claims: [Services/**]
    description: 业务服务层(依赖注入容器)
  - kid: P5.K3
    name: models
    file_claims: [Models/**]
    description: 数据模型 / DTO
  - kid: P5.K4
    name: websocket
    file_claims: [WebSocket/**]
    description: WS 核心(连接管理 / 消息分发)
  - kid: P5.K5
    name: routes
    file_claims: [Routes/**]
    description: WS 路由(refresh_link 在这)
  - kid: P5.K6
    name: interop
    file_claims: [Interop/**]
    description: 与 dsp_algo (P/Invoke) + pysidecar (subprocess) 互操作
  - kid: P5.K7
    name: aiagent
    file_claims: [AIAgent/**]
    description: AI 代理子系统
  - kid: P5.K8
    name: extensions
    file_claims: [Extensions/**]
    description: C# 扩展方法集合
  - kid: P5.K9
    name: data-persistence
    file_claims: [data/**]
    description: 数据持久化层(SQLite / JSON 文件 / etc.)

5.3 P6-dsp-algo 详细 K-thread 列表(v0.3 新增)

kernel_threads:
  - kid: P6.K1
    name: framework
    file_claims: [framework/**]
    description: DSP 框架层(模块抽象 / pipeline)
  - kid: P6.K2
    name: modules
    file_claims: [modules/**]
    description: 各 DSP 模块(EQ/Compressor/Reverb/...)· 不下沉到单算法粒度
  - kid: P6.K3
    name: platform
    file_claims: [platform/**]
    description: 跨平台抽象(Win/Linux/Mac)
  - kid: P6.K4
    name: include
    file_claims: [include/**]
    description: 头文件接口(C ABI · 暴露给 P5.K6 调用)
  - kid: P6.K5
    name: build-system
    file_claims: [make/**, build/**]
    description: 构建系统(make + cmake + 产物)
  - kid: P6.K6
    name: config
    file_claims: [config/**]
    description: 模块配置文件

5.4 P7-pysidecar 详细 K-thread 列表(v0.3 新增 · 仅户口登记)

kernel_threads:
  - kid: P7.K1
    name: analyzer
    file_claims: [analyzer/**]
    description: 数据分析模块
  - kid: P7.K2
    name: reporter
    file_claims: [reporter/**]
    description: 报告生成
  - kid: P7.K3
    name: scripts
    file_claims: [scripts/**]
    description: 工具脚本

user_threads: []   # v0.3 实施期暂无任务派发 · 待 ADR-NN 触发再 fork

5.5 P_contracts 详细 K-thread 列表(v0.3 独立提升)

# processes/P_contracts/PROCESS.md
pid: P_contracts
name: contracts
type: daemon
state: running
priority: P-1                # 系统级 · 最高优先级

kernel_threads:
  - kid: P_contracts.K1
    name: protocol-v1
    file_claims: [contracts/protocol-v1.md]
    description: |
      跨栈 IPC 协议规范(类比 syscall 表)。
      所有 P1-P4 / P5-P7 之间的跨栈引用必须通过本文件桥接。
      ⚠️ HARD-DEADLINE Day 5 EOD freeze
    write_permission: ClaudeB-only   # 沿用 v3 ADR-AIOS-01
    last_modified_by: (待 B1 commit)

6. IPC 协议(进程间通信 · v0.3 系统调用表)

6.1 IPC 通道分类

通道类型	用法	v0.3 全栈示例
via P_contracts.K1	标准跨栈 IPC(必走)	P3 → P5 调 refresh-link API · P2 → P6 codegen
via shared K-thread	同栈跨进程读共享栈	P3 读 P0.K-shared-types · 不写
via arch-event	架构事件单向广播	ADR-AIOS-05 → P5/P_contracts/P0 多播
none	进程内闭环(K-thread 仅自身)	P3.U2 仅占 P3.K5+P3.K7(无跨进程)

6.2 跨栈 IPC 强制走 P_contracts(v0.3 铁律)

v0.3 关键约束:

任何前端 P1-P4 → 后端 P5/P6/P7 的引用 · 任何后端服务之间 (P5↔P6↔P7) 的引用 · 必须在 PCB.ipc_channels 中声明 via: P_contracts.K1-protocol-v1,并且实际代码引用必须能在 contracts/protocol-v1.md 找到对应章节。

反例(v0.3 禁止):

# ❌ 错误:P3 直接引用 P5 内部 API · 跳过 contracts
ipc_channels:
  - to: P5-backend-csharp
    via: direct-http     # ❌ 禁止

正例:

# ✅ 正确:走 P_contracts 桥接
ipc_channels:
  - to: P5-backend-csharp
    via: P_contracts.K1-protocol-v1
    section: §5 refresh-link 协议
    purpose: 触发 backend 重建链路图

6.3 共享 K-thread 的读写权限

P0 daemon 持有的 K-shared-* 通过 shared_resources.access 字段控制读写:

shared_resources:
  - via: P0.K-shared-types
    files: [types/tuningMode.ts]
    access: read-write          # 此 U-thread 会写 · 必须 occupies 中含 P0.K-shared-types
  - via: P1.K7
    files: [stores/linkStore.ts]
    access: read-only           # 仅读 · 不需 occupies(但需在此声明)

7. RUNQ 就绪队列概念(详见 Scheduling-Algorithm.md)

7.1 RUNQ 行结构

| 优先级 | PID.UID                  | U-thread Name        | Occupies(K 集合)              | Bound CPU      | Affinity |
|--------|--------------------------|----------------------|--------------------------------|----------------|----------|
| P-1    | P_contracts.U-freeze-tag | freeze-protocol-v1   | P_contracts.K1                 | ClaudeB        | hot      |
| P0     | P5.U-refresh-link        | refresh-link-finalize| P5.K4+P5.K5+P_contracts.K1     | Copilot-Worker | hot      |
| P0     | P2.U5                    | module-uid-namespace | P2.K7+P0.K-shared-types        | ClaudeA        | hot      |
| ...    | ...                      | ...                  | ...                            | ...            | ...      |

7.2 RUNQ 与 PCB 的同步关系

PCB(processes/<pid>/PROCESS.md)= 真值源 · 含全部 K + U + 历史 zombie
RUNQ.md = 视图 · 仅展示 state==ready && blocked_on==null 的 U-thread + 当前 running U-thread
每日 standup 由 AIOS 跑一次 RUNQ 重算(详见 Scheduling-Algorithm.md §3)

8. 文件目录约定(对齐 ADR-06 §2.4 v0.3)

v0.3 关键调整(2026-05-26 17:42 拍板):processes/ 根目录归 docs/08-implementation/40-aios/processes/ · 与 ADR/agents/PCB/RUNQ 同居 · 不再放在 30-frontend-vue3/ 下(避免后端/DSP/pysidecar 进程语义错位)。

docs/08-implementation/40-aios/processes/<pid>-<name>/
├── PROCESS.md                    ← PCB(本文件 §4 schema)
├── kernel_threads/
│   ├── K1-<name>/
│   │   └── THREAD.md             ← K-thread 描述符(file_claims + last_modified_by)
│   ├── K2-<name>/
│   ...
└── user_threads/
    ├── U1-<name>/
    │   ├── STEP-A-...md          ← 拆分 step 文档(原 PROMPT 内容)
    │   ├── STEP-B-...md
    │   └── README.md             ← U-thread 总览(uid/state/occupies)
    ...

命名约束: - K<N>-<name> 中 N 从 1 起递增 · <name> 用 kebab-case - P0 的 K-shared-* 是特例(不走 K1/K2 编号 · 直接 K-shared-types/contracts/test-aux) - U<N>-<name> 中 N 与 PROCESS.md 的 user_threads.uid 严格对应(P3.U2 → U2-tuning-mode-ui/)

全栈 10 进程目录(v0.3):

docs/08-implementation/40-aios/processes/
├── P0-xishell/         (daemon · 9 K)
├── P1-xilink/          (user-process · 7 K)
├── P2-xiforge/         (user-process · 7 K · ADR-04)
├── P3-xitune/          (user-process · 7 K · ADR-05 主载体)
├── P4-xitest/          (user-process · 6 K · 当前 blocked)
├── P5-backend-csharp/  (daemon · 9 K · v0.3 新增)
├── P6-dsp-algo/        (daemon · 6 K · v0.3 新增)
├── P7-pysidecar/       (daemon · 3 K · v0.3 新增 · 仅户口登记)
├── P_contracts/        (daemon · 1 K · v0.3 独立提升 · ClaudeB 写独占)
└── P_arch/             (arch-event 容器 · 0 K · 仅 user_threads)

9. 与历史模型的映射(v3 angle 视角)

旧术语	新术语
ClaudeA 独占 17 phase	P1-P4 user-process · K-thread 持有 stage 文件所有权 · 任何 CPU 可派 U-thread
ClaudeB 独占 backend_csharp/	P5 daemon · K1-K9 持有 9 个 namespace · ClaudeB 是默认主战场 CPU(非独占)
KANBAN §1.x ClaudeC	P3.user_threads + P_arch/ADR-NN.user_threads(架构事件归 P_arch · 业务任务归对应 P)
shared/types/contracts/test-aux	P0 daemon 持有 K-shared-types/contracts/test-aux 三个 K-thread
contracts/protocol-v1.md	P_contracts daemon · K1-protocol-v1(v0.3 独立提升 · 类比 syscall 表)

10. 验收清单

任何新建 / 修改进程时需通过以下校验(后续可机器化):

processes/<pid>-<name>/PROCESS.md 存在 · frontmatter 含 pid/name/type/state/priority
kernel_threads 数组每项含 kid/name/state/file_claims
user_threads 数组每项含 uid/name/state/occupies
每个 occupies 中的 K-thread 都能在某个进程的 kernel_threads 中找到(全局唯一 KID)
共享栈引用(shared_resources.via)指向真实存在的 K-thread
跨栈 IPC 全部声明 via=P_contracts.K1-protocol-v1(v0.3 铁律)
U-thread.files 必须 ⊆ U-thread.occupies 所列所有 K-thread.file_claims 的并集
PROCESS.md frontmatter 的 last_modified 与最近 user_threads 完成时间一致

11. 文档元信息

创建:2026-05-26 17:10 · Step B · T2(ADR-AIOS-06 v0.3 实施)
版本:v1.0(对齐 ADR-AIOS-06 v0.3)
后续修订:仅在 ADR-AIOS-NN 明确变更进程模型时追加版本(v1.x → v2.0)
同栈姊妹文档:Scheduling-Algorithm.md / Commit-Convention.md / Concurrency-Domains.md