yingqi-z20-Agent-libOS

repository

loading code, commits, and activity

repositories

loading repo index

#1	# Agent libOS 设计文档（本文档部分内容可能已经过时）
#2
#3	## 0. 文档目的
#4
#5	本文档用于指导团队实现一个以 Agent Process 为核心抽象的 Agent libOS 框架。该框架不以传统 LLM 聊天界面为中心，而是将
#6	Agent 建模为长期运行、可调度、可中断、可扩展、可审计的执行主体。
#7
#8	系统目标是提供一组 Agent-native 的运行时原语，使 Agent 能够：
#9
#10	- 作为进程长期运行；
#11	- fork 子 Agent；
#12	- exec 到新的执行镜像；
#13	- 动态加载 skills；
#14	- 在受控条件下 JIT 生成并注册新工具；
#15	- 使用对象化内存，而不是字节寻址内存或文件系统目录树；
#16	- 将人类建模为可访问、可授权、可发送中断的外部对象；
#17	- 通过 capability、安全沙箱、审计日志和 checkpoint/rollback 机制控制风险。
#18
#19	本文档面向开发团队，重点说明系统边界、核心模块、数据模型、API、执行语义、安全约束和实现路线。
#20
#21	---
#22
#23	## 1. 设计原则
#24
#25	### 1.1 Agent 是运行主体，不是对话响应器
#26
#27	传统 Chatbot 架构通常是：
#28
#29	```text
#30	Human -> Chat Loop -> Agent -> Tools
#31	```
#32
#33	本系统采用 Agent-centric 架构：
#34
#35	```text
#36	Agent Process -> Tools / Skills / Memory / HumanObject / Primitives
#37	```
#38
#39	人类不是每一步主循环的驱动者，而是 Agent libOS 中的一类特殊 primitive：Agent 可以主动访问人，人也可以通过中断机制影响 Agent。HumanObject 负责请求队列、审批、唤醒、审计与 capability 语义；具体终端或 UI 的读写落在 Resource Provider Substrate 的 `HumanProvider` 上。
#40
#41	### 1.2 Agent Process 而非 Workflow Thread
#42
#43	本框架的核心抽象不是 workflow run，而是 Agent Process。
#44
#45	Agent Process 应具有：
#46
#47	- 稳定身份：`pid`；
#48	- 父子关系：`parent_pid`；
#49	- 执行镜像：`AgentImage`；
#50	- 当前目标：`Goal`；
#51	- 当前状态：`ProcessState`；
#52	- 对象化工作集：`MemoryView`；
#53	- 能力集合：`CapabilitySet`；
#54	- 已加载技能：`SkillSet`；
#55	- 工具句柄表：`ToolHandleTable`；
#56	- 事件队列：`EventQueue`；
#57	- 审计日志：`AuditLog`；
#58	- checkpoint/rollback 能力。
#59
#60	### 1.3 Object Memory，而不是 byte-addressed memory
#61
#62	Agent 的内存不应模拟虚拟地址空间。Agent 处理的是计划、证据、观察、工具结果、代码补丁、人类决策、任务状态和技能对象，而不是裸字节。
#63
#64	内存应实现为：
#65
#66	```text
#67	Typed Object Store + Object Graph + Capability Handles + Memory Views + Context Materialization
#68	```
#69
#70	文件系统只是外部对象适配器之一，不是整个系统的根抽象。
#71
#72	### 1.4 Everything is object/event/capability，不是 everything is file
#73
#74	统一性来自三件事：
#75
#76	- object：所有可引用实体都有对象身份；
#77	- event：所有状态变化和异步交互都通过事件传播；
#78	- capability：所有访问、修改、副作用和扩展都受 capability 管控。
#79
#80	### 1.5 Agent 可以自扩展，但不能自授权
#81
#82	Agent 可以提出：
#83
#84	- fork 子 Agent；
#85	- exec 到新镜像；
#86	- load skill；
#87	- propose JIT tool。
#88
#89	但它不能绕过 runtime 的 capability manager、tool broker、sandbox、policy checker 和 human approval。
#90
#91	核心原则：
#92
#93	> Agent may propose capability expansion, but the runtime decides whether to grant it.
#94
#95	### 1.6 所有外部副作用必须可追踪
#96
#97	包括：
#98
#99	- 文件写入；
#100	- shell 命令；
#101	- 网络请求；
#102	- API 调用；
#103	- 发邮件；
#104	- 创建日程；
#105	- 写数据库；
#106	- 注册工具；
#107	- 加载技能；
#108	- 修改长期记忆；
#109	- 人类授权；
#110	- capability grant/revoke。
#111
#112	所有这些都必须进入 audit log。
#113
#114	---
#115
#116	## 2. 总体架构
#117
#118	### 2.1 分层结构
#119
#120	```text
#121	+------------------------------------------------------------+
#122	\| Agent Applications / Personalities \|
#123	\| CodingAgent / ResearchAgent / EDAAgent / TutorAgent \|
#124	+------------------------------------------------------------+
#125	\| Skills / Tools Layer \|
#126	\| LLM-facing actions, skills, tool bundles, workflows \|
#127	\| Wrap and compose libOS primitives into usable affordances \|
#128	+------------------------------------------------------------+
#129	\| Agent LibOS \|
#130	\| Process API / Object Memory API / Event API / Human API \|
#131	\| Skill Loader / Tool Broker Interface / Context Materializer\|
#132	+------------------------------------------------------------+
#133	\| Agent Kernel ABI \|
#134	\| Process / Event / Capability / Object / Checkpoint / Audit \|
#135	+------------------------------------------------------------+
#136	\| Host Runtime \|
#137	\| Container Sandbox / LLM API / DB / Queue / Object Store \|
#138	\| External Service Adapters / Human UI / Policy Engine \|
#139	+------------------------------------------------------------+
#140	```
#141
#142	Skills / Tools Layer 是面向 LLM 暴露的 action surface，负责把 libOS 的低层原语组合、约束和文档化，使模型能够以稳定、可理解、可验证的方式使用系统能力。
#143
#144	类比传统系统：
#145
#146	```text
#147	Application
#148	-> libc / language runtime / standard library
#149	-> syscall ABI
#150	-> kernel
#151	```
#152
#153	在本系统中对应为：
#154
#155	```text
#156	Agent Personality
#157	-> Skills / Tools Layer
#158	-> Agent LibOS API
#159	-> Agent Kernel ABI / Host Runtime
#160	```
#161
#162	### 2.2 核心组件
#163
#164	```text
#165	AgentRuntime
#166	├── ProcessManager
#167	├── Scheduler
#168	├── EventBus
#169	├── CapabilityManager
#170	├── ObjectMemoryManager
#171	├── ContextMaterializer
#172	├── SkillLoader
#173	├── ToolBrokerInterface
#174	├── HumanObjectManager
#175	├── CheckpointManager
#176	├── Primitive Managers
#177	├── AuditManager
#178	└── PolicyEngine
#179
#180	SkillsToolsLayer
#181	├── SkillRegistry
#182	├── ToolRegistry
#183	├── ToolBundleManager
#184	├── ActionSchemaCompiler
#185	├── Prompt/Instruction Packager
#186	├── Workflow Macro Library
#187	├── Tool Selection Metadata
#188	└── Adapter Library
#189	```
#190
#191	需要区分：
#192
#193	- `AgentRuntime` 提供底层可执行、安全、状态和审计能力；
#194	- `SkillsToolsLayer` 提供 LLM 可用的高层动作、工具描述、技能说明、组合宏和领域适配器；
#195	- `Agent Applications / Personalities` 选择、配置和约束某一类任务所需的 skills/tools。
#196
#197	### 2.3 Skills / Tools Layer 的职责
#198
#199	Skills / Tools Layer 位于 Agent personality 与 Agent LibOS 之间，承担类似 libc、语言运行时和标准库的职责。
#200
#201	它的主要职责包括：
#202
#203	1. 封装底层原语
#204
#205	将低层 libOS 调用包装为 LLM 可理解的动作。
#206
#207	例如：
#208
#209	```text
#210	spawn_log_analysis_worker(log_object)
#211	= create_view(log_object, read_only)
#212	+ fork(mode=WORKER)
#213	+ wait(child)
#214	+ merge_view(child_result)
#215	```
#216
#217	2. 定义 LLM-facing action schema
#218
#219	每个暴露给模型的 tool/action 都必须有清晰的：
#220
#221	- 名称；
#222	- 使用场景；
#223	- 输入 schema；
#224	- 输出 schema；
#225	- 权限需求；
#226	- 副作用说明；
#227	- 失败模式；
#228	- 示例。
#229
#230	3. 组合常用工作流
#231
#232	将多步 libOS 操作组合为稳定的 macro-action。
#233
#234	例如：
#235
#236	```text
#237	run_tests_and_summarize(test_command)
#238	inspect_process_status(pid)
#239	rollback_to_last_safe_checkpoint()
#240	```
#241
#242	4. 隔离模型与底层复杂性
#243
#244	Agent 不应直接调用 `capability.grant`、`checkpoint.restore`、`memory.merge_view` 等危险或复杂原语，尽管原语内部有
#245	PolicyEngine 检查。此类能力应通过受限 tool 或 skill 暴露。
#246
#247	5. 支持领域专用能力包
#248
#249	不同 Agent personality 可以加载不同 tool bundles：
#250
#251	```text
#252	Coding Tool Bundle
#253	- read_repo_structure
#254	- analyze_test_failure
#255	- propose_patch
#256	- run_tests
#257	- request_patch_approval
#258
#259	Research Tool Bundle
#260	- search_papers
#261	- extract_claims
#262	- compare_methods
#263	- build_bibliography
#264
#265	EDA Tool Bundle
#266	- run_cli_command
#267	- parse_waveform
#268	- inspect_timing_report
#269	- request_design_decision
#270	```
#271
#272	6. 作为 JIT tool 的落点
#273
#274	Agent 生成的新工具不应直接进入 libOS，而应进入 Skills / Tools Layer 的 registry。ToolBroker 负责验证和注册，Skills /
#275	Tools Layer 负责将其包装成 LLM 可用 action。
#276
#277	### 2.4 关键数据流
#278
#279	#### 2.4.1 Agent 执行一轮
#280
#281	```text
#282	ProcessManager selects runnable AgentProcess
#283	-> Scheduler grants execution budget
#284	-> ContextMaterializer materializes selected MemoryView
#285	-> LLM/Planner produces action
#286	-> Runtime validates action through PolicyEngine
#287	-> Action dispatched to Tool/Skill/Memory/Human/Event subsystem
#288	-> Result written as Object + Event + Audit record
#289	-> Process state updated
#290	```
#291
#292	#### 2.4.2 Agent 请求人类授权
#293
#294	```text
#295	AgentProcess proposes high-risk action
#296	-> CapabilityManager detects missing capability
#297	-> HumanObjectManager creates HumanRequestObject
#298	-> EventBus emits human_query event
#299	-> Process moves to WAITING_HUMAN or continues with alternative path
#300	-> Human replies approve/reject/edit
#301	-> EventBus emits human_response event
#302	-> CapabilityManager grants/rejects capability
#303	-> Process resumes or replans
#304	```
#305
#306	#### 2.4.3 Agent JIT 生成工具
#307
#308	```text
#309	AgentProcess proposes ToolCandidateObject
#310	-> ToolBroker builds in sandbox
#311	-> Static analysis + unit tests + permission analysis
#312	-> PolicyEngine evaluates risk
#313	-> Optional HumanObject approval
#314	-> ToolRegistry signs and registers executable tool
#315	-> Skills / Tools Layer wraps tool as LLM-facing action
#316	-> Agent receives ToolHandle with attenuated capabilities
#317	```
#318
#319	---
#320
#321	## 3. 核心抽象
#322
#323	## 3.1 AgentProcess
#324
#325	### 3.1.1 定义
#326
#327	AgentProcess 是系统中可调度的长期运行主体。
#328
#329	```python
#330	@dataclass
#331	class AgentProcess:
#332	pid: PID
#333	parent_pid: PID \| None
#334	image: AgentImageRef
#335	state: ProcessState
#336	goal: ObjectHandle
#337	memory_view: MemoryView
#338	capabilities: CapabilitySet
#339	loaded_skills: dict[SkillID, SkillHandle]
#340	tool_table: dict[ToolID, ToolHandle]
#341	event_cursor: EventCursor
#342	checkpoint_head: CheckpointID \| None
#343	status: ProcessStatus
#344	message_queue: ProcessMessageQueue
#345	resource_budget: ResourceBudget
#346	created_at: Timestamp
#347	updated_at: Timestamp
#348	```
#349
#350	### 3.1.2 ProcessStatus
#351
#352	```python
#353	class ProcessStatus(Enum):
#354	CREATED = "created"
#355	RUNNABLE = "runnable"
#356	RUNNING = "running"
#357	WAITING_EVENT = "waiting_event"
#358	WAITING_TOOL = "waiting_tool"
#359	WAITING_HUMAN = "waiting_human"
#360	PAUSED = "paused"
#361	SUSPENDED = "suspended"
#362	EXITED = "exited"
#363	FAILED = "failed"
#364	KILLED = "killed"
#365	```
#366
#367	### 3.1.3 Process 原语
#368
#369	```python
#370	class ProcessAPI:
#371	def fork(
#372	self,
#373	parent: PID,
#374	goal: ObjectHandle,
#375	memory_view: MemoryViewSpec,
#376	capabilities: CapabilitySpec,
#377	image: AgentImageRef \| None = None,
#378	mode: ForkMode = ForkMode.RESTRICTED,
#379	) -> PID: ...
#380
#381	def exec(
#382	self,
#383	pid: PID,
#384	image: AgentImageRef,
#385	args: dict,
#386	preserve_memory: bool = True,
#387	preserve_capabilities: bool = False,
#388	) -> None: ...
#389
#390	def wait(self, pid: PID, child: PID, timeout: Duration \| None = None) -> ProcessResult: ...
#391
#392	def signal(self, target: PID, signal: ProcessSignal, payload: dict \| None = None) -> None: ...
#393
#394	def send_message(
#395	self,
#396	sender: PID,
#397	recipient: PID,
#398	kind: Literal["normal", "interrupt"],
#399	subject: str,
#400	body: str,
#401	payload: dict \| None = None,
#402	) -> ProcessMessageID: ...
#403
#404	def read_messages(
#405	self,
#406	pid: PID,
#407	include_acked: bool = False,
#408	ack: bool = True,
#409	) -> list[ProcessMessage]: ...
#410
#411	def pause(self, pid: PID, reason: str) -> None: ...
#412
#413	def resume(self, pid: PID) -> None: ...
#414
#415	def cancel(self, pid: PID, reason: str) -> None: ...
#416
#417	def exit(self, pid: PID, result: ObjectHandle \| None = None) -> None: ...
#418	```
#419
#420	### 3.1.4 fork 语义
#421
#422	支持四种 fork 模式：
#423
#424	```python
#425	class ForkMode(Enum):
#426	COPY = "copy"
#427	RESTRICTED = "restricted"
#428	SPECULATIVE = "speculative"
#429	WORKER = "worker"
#430	```
#431
#432	#### COPY
#433
#434	子进程继承父进程较完整的 memory view，但 capability 默认仍需 attenuate。
#435
#436	用于：同级分支探索、可控可信任务。
#437
#438	#### RESTRICTED
#439
#440	子进程只获得显式指定对象和最小权限。
#441
#442	用于：默认安全模式。
#443
#444	#### SPECULATIVE
#445
#446	子进程用于探索，不允许产生外部副作用，结果需 merge 才能进入主线。
#447
#448	用于：多方案并行、代码修复尝试、计划搜索。
#449
#450	#### WORKER
#451
#452	子进程只执行封闭任务，无长期记忆写入权限。
#453
#454	用于：日志分析、测试运行、局部检索、格式转换。
#455
#456	### 3.1.5 exec 语义
#457
#458	`exec` 替换进程执行镜像，但不必替换全部状态。
#459
#460	执行镜像包括：
#461
#462	- LLM context；
#463	- system instruction；
#464	- planner strategy；
#465	- default skills；
#466	- default tools；
#467	- context materialization policy；
#468	- safety policy profile；
#469	- output/action protocol。
#470
#471	`exec` 必须经过：
#472
#473	- image signature check；
#474	- policy compatibility check；
#475	- capability preservation check；
#476	- state migration check；
#477	- audit record。
#478
#479	默认规则：
#480
#481	```text
#482	exec 不自动提升 capability。
#483	exec 后 capability 只能保持不变或收缩。
#484	需要新 capability 时必须显式 request。
#485	```
#486
#487	---
#488
#489	## 3.2 AgentImage
#490
#491	### 3.2.1 定义
#492
#493	AgentImage 是 Agent Process 的执行镜像，类似可执行文件或容器镜像。
#494
#495	```python
#496	@dataclass(frozen=True)
#497	class AgentImage:
#498	image_id: AgentImageID
#499	name: str
#500	version: str
#501	system_prompt: str
#502	planner: PlannerSpec
#503	action_schema: ActionSchema
#504	default_skills: list[SkillRef]
#505	default_tools: list[ToolRef]
#506	context_policy: ContextPolicy
#507	safety_profile: SafetyProfile
#508	required_capabilities: list[CapabilityRequirement]
#509	metadata: dict
#510	signature: Signature \| None
#511	```
#512
#513	### 3.2.2 镜像类型
#514
#515	推荐内置以下镜像：
#516
#517	- `base-agent`：通用任务执行；
#518	- `coding-agent`：软件工程任务；
#519	- `research-agent`：文献调研；
#520	- `eda-agent`：EDA/CLI 操作；
#521	- `toolmaker-agent`：工具生成与测试；
#522	- `review-agent`：审查、验证、安全分析；
#523	- `summarizer-agent`：摘要压缩；
#524	- `human-coordinator-agent`：人类交互协调。
#525
#526	---
#527
#528	## 3.3 Object Memory
#529
#530	## 3.3.1 设计目标
#531
#532	Object Memory 是 Agent libOS 的核心内存系统。
#533
#534	它应支持：
#535
#536	- typed objects；
#537	- object graph；
#538	- versioning；
#539	- provenance；
#540	- capability-protected access；
#541	- snapshots；
#542	- memory views；
#543	- fork/merge；
#544	- semantic query；
#545	- context materialization。
#546
#547	### 3.3.2 AgentObject
#548
#549	```python
#550	@dataclass(frozen=True)
#551	class AgentObject:
#552	oid: OID
#553	type: ObjectType
#554	schema_version: str
#555	payload: bytes \| dict \| str
#556	metadata: ObjectMetadata
#557	provenance: Provenance
#558	version: int
#559	immutable: bool
#560	created_by: PID \| SystemActor
#561	created_at: Timestamp
#562	updated_at: Timestamp
#563	```
#564
#565	### 3.3.3 ObjectMetadata
#566
#567	```python
#568	@dataclass
#569	class ObjectMetadata:
#570	title: str \| None
#571	summary: str \| None
#572	tags: list[str]
#573	mime_type: str \| None
#574	token_estimate: int \| None
#575	embedding_refs: list[EmbeddingRef]
#576	indexes: list[IndexRef]
#577	sensitivity: SensitivityLevel
#578	retention_policy: RetentionPolicy
#579	```
#580
#581	### 3.3.4 常见 ObjectType
#582
#583	```python
#584	class ObjectType(Enum):
#585	TASK = "task"
#586	GOAL = "goal"
#587	PLAN = "plan"
#588	STEP = "step"
#589	CONSTRAINT = "constraint"
#590	MESSAGE = "message"
#591	HUMAN_DECISION = "human_decision"
#592	HUMAN_REQUEST = "human_request"
#593	TOOL_RESULT = "tool_result"
#594	OBSERVATION = "observation"
#595	ERROR_TRACE = "error_trace"
#596	CODE_PATCH = "code_patch"
#597	TEST_RESULT = "test_result"
#598	EVIDENCE = "evidence"
#599	CLAIM = "claim"
#600	SUMMARY = "summary"
#601	SKILL = "skill"
#602	TOOL_SPEC = "tool_spec"
#603	TOOL_CANDIDATE = "tool_candidate"
#604	TOOL_ARTIFACT = "tool_artifact"
#605	CHECKPOINT = "checkpoint"
#606	PROCESS_STATE = "process_state"
#607	EXTERNAL_REF = "external_ref"
#608	ARTIFACT = "artifact"
#609	```
#610
#611	### 3.3.5 ObjectHandle
#612
#613	OID 不代表访问权限。Agent Process 必须通过 capability handle 访问对象。
#614
#615	```python
#616	@dataclass(frozen=True)
#617	class ObjectHandle:
#618	oid: OID
#619	rights: set[ObjectRight]
#620	capability_id: CapabilityID
#621	expires_at: Timestamp \| None
#622	```
#623
#624	```python
#625	class ObjectRight(Enum):
#626	READ = "read"
#627	WRITE = "write"
#628	LINK = "link"
#629	DIFF = "diff"
#630	MATERIALIZE = "materialize"
#631	DELETE = "delete"
#632	GRANT = "grant"
#633	```
#634
#635	### 3.3.6 Object Graph
#636
#637	对象之间通过 typed links 形成图。
#638
#639	```python
#640	@dataclass(frozen=True)
#641	class ObjectLink:
#642	src: OID
#643	relation: RelationType
#644	dst: OID
#645	metadata: dict
#646	created_by: PID \| SystemActor
#647	created_at: Timestamp
#648	```
#649
#650	常见关系：
#651
#652	```python
#653	class RelationType(Enum):
#654	HAS_PLAN = "has_plan"
#655	HAS_STEP = "has_step"
#656	CONSTRAINED_BY = "constrained_by"
#657	SUPPORTED_BY = "supported_by"
#658	PRODUCED = "produced"
#659	EVALUATED_BY = "evaluated_by"
#660	DERIVED_FROM = "derived_from"
#661	SUMMARIZES = "summarizes"
#662	REFERENCES = "references"
#663	APPROVED_BY = "approved_by"
#664	REJECTED_BY = "rejected_by"
#665	SUPERSEDES = "supersedes"
#666	BLOCKED_BY = "blocked_by"
#667	ASSIGNED_TO = "assigned_to"
#668	```
#669
#670	### 3.3.7 MemoryView
#671
#672	MemoryView 是 Agent Process 当前可见对象集合。
#673
#674	```python
#675	@dataclass
#676	class MemoryView:
#677	view_id: MemoryViewID
#678	owner_pid: PID
#679	roots: list[ObjectHandle]
#680	filters: list[ObjectFilter]
#681	rights_policy: ViewRightsPolicy
#682	created_from: MemoryViewID \| SnapshotID \| None
#683	mode: ViewMode
#684	```
#685
#686	```python
#687	class ViewMode(Enum):
#688	READ_ONLY = "read_only"
#689	COPY_ON_WRITE = "copy_on_write"
#690	MUTABLE = "mutable"
#691	EPHEMERAL = "ephemeral"
#692	```
#693
#694	### 3.3.8 Object Memory API
#695
#696	```python
#697	class ObjectMemoryAPI:
#698	def create_object(
#699	self,
#700	pid: PID,
#701	type: ObjectType,
#702	payload: Any,
#703	metadata: ObjectMetadata \| None = None,
#704	immutable: bool = True,
#705	) -> ObjectHandle: ...
#706
#707	def get_object(self, pid: PID, handle: ObjectHandle) -> AgentObject: ...
#708
#709	def update_object(
#710	self,
#711	pid: PID,
#712	handle: ObjectHandle,
#713	patch: ObjectPatch,
#714	) -> ObjectHandle: ...
#715
#716	def link_objects(
#717	self,
#718	pid: PID,
#719	src: ObjectHandle,
#720	relation: RelationType,
#721	dst: ObjectHandle,
#722	metadata: dict \| None = None,
#723	) -> None: ...
#724
#725	def query_objects(
#726	self,
#727	pid: PID,
#728	query: ObjectQuery,
#729	) -> list[ObjectHandle]: ...
#730
#731	def create_view(
#732	self,
#733	pid: PID,
#734	roots: list[ObjectHandle],
#735	mode: ViewMode,
#736	filters: list[ObjectFilter] \| None = None,
#737	) -> MemoryView: ...
#738
#739	def fork_view(
#740	self,
#741	parent_pid: PID,
#742	child_pid: PID,
#743	parent_view: MemoryView,
#744	spec: MemoryViewSpec,
#745	) -> MemoryView: ...
#746
#747	def merge_view(
#748	self,
#749	parent_pid: PID,
#750	child_view: MemoryView,
#751	policy: MergePolicy,
#752	) -> MergeResult: ...
#753
#754	def snapshot_view(self, pid: PID, view: MemoryView) -> SnapshotID: ...
#755
#756	def materialize_context(
#757	self,
#758	pid: PID,
#759	view: MemoryView,
#760	policy: ContextPolicy,
#761	budget_tokens: int,
#762	) -> MaterializedContext: ...
#763	```
#764
#765	### 3.3.9 Context Materialization
#766
#767	LLM 不能直接访问整个 Object Store。每次模型调用前，ContextMaterializer 将 MemoryView 转换为模型上下文。
#768
#769	```python
#770	@dataclass
#771	class MaterializedContext:
#772	text: str
#773	object_refs: list[OID]
#774	token_count: int
#775	omitted_objects: list[OID]
#776	policy_used: ContextPolicy
#777	```
#778
#779	Materialization 策略：
#780
#781	- `evidence_first`：证据优先；
#782	- `recency_first`：最近对象优先；
#783	- `plan_first`：计划与当前状态优先；
#784	- `error_debug`：错误日志与相关代码优先；
#785	- `human_constraints_first`：人类约束和授权优先；
#786	- `minimal`：只放入任务必要对象；
#787	- `full_debug`：尽可能完整，用于调试。
#788
#789	---
#790
#791	## 3.4 Event System
#792
#793	### 3.4.1 设计目标
#794
#795	Event System 负责处理：
#796
#797	- 进程间通信；
#798	- 人类中断；
#799	- 工具返回；
#800	- capability 变化；
#801	- 定时器；
#802	- checkpoint；
#803	- 子进程退出；
#804	- 外部环境变化。
#805
#806	### 3.4.2 Event
#807
#808	```python
#809	@dataclass(frozen=True)
#810	class Event:
#811	event_id: EventID
#812	type: EventType
#813	source: ActorRef
#814	target: ActorRef \| None
#815	payload: dict
#816	priority: EventPriority
#817	created_at: Timestamp
#818	correlation_id: CorrelationID \| None
#819	causality: list[EventID]
#820	```
#821
#822	### 3.4.3 EventType
#823
#824	```python
#825	class EventType(Enum):
#826	PROCESS_CREATED = "process_created"
#827	PROCESS_EXITED = "process_exited"
#828	PROCESS_FAILED = "process_failed"
#829	PROCESS_SIGNAL = "process_signal"
#830
#831	TOOL_CALL_REQUESTED = "tool_call_requested"
#832	TOOL_CALL_RESULT = "tool_call_result"
#833	TOOL_CALL_FAILED = "tool_call_failed"
#834
#835	HUMAN_QUERY = "human_query"
#836	HUMAN_RESPONSE = "human_response"
#837	HUMAN_INTERRUPT = "human_interrupt"
#838	HUMAN_APPROVAL = "human_approval"
#839	HUMAN_REJECTION = "human_rejection"
#840
#841	CAPABILITY_GRANTED = "capability_granted"
#842	CAPABILITY_REVOKED = "capability_revoked"
#843	CAPABILITY_DENIED = "capability_denied"
#844
#845	SKILL_LOADED = "skill_loaded"
#846	SKILL_UNLOADED = "skill_unloaded"
#847
#848	CHECKPOINT_CREATED = "checkpoint_created"
#849	ROLLBACK_PERFORMED = "rollback_performed"
#850
#851	MEMORY_OBJECT_CREATED = "memory_object_created"
#852	MEMORY_OBJECT_UPDATED = "memory_object_updated"
#853	MEMORY_VIEW_MERGED = "memory_view_merged"
#854
#855	TIMER_EXPIRED = "timer_expired"
#856	POLICY_VIOLATION = "policy_violation"
#857	RESOURCE_EXHAUSTED = "resource_exhausted"
#858	```
#859
#860	### 3.4.4 Event API
#861
#862	```python
#863	class EventAPI:
#864	def send(
#865	self,
#866	source: ActorRef,
#867	target: ActorRef,
#868	type: EventType,
#869	payload: dict,
#870	priority: EventPriority = EventPriority.NORMAL,
#871	) -> EventID: ...
#872
#873	def recv(
#874	self,
#875	pid: PID,
#876	filter: EventFilter \| None = None,
#877	timeout: Duration \| None = None,
#878	) -> Event \| None: ...
#879
#880	def poll(self, pid: PID, filter: EventFilter \| None = None) -> list[Event]: ...
#881
#882	def subscribe(self, pid: PID, filter: EventFilter) -> SubscriptionID: ...
#883
#884	def interrupt(
#885	self,
#886	source: ActorRef,
#887	target_pid: PID,
#888	signal: ProcessSignal,
#889	payload: dict \| None = None,
#890	priority: EventPriority = EventPriority.HIGH,
#891	) -> EventID: ...
#892
#893	def ack(self, pid: PID, event_id: EventID) -> None: ...
#894	```
#895
#896	### 3.4.5 中断语义
#897
#898	中断分为四类：
#899
#900	\| 类型 \| 处理方式 \| 示例 \|
#901	\|---------------\|--------\|---------------\|
#902	\| Immediate \| 立即抢占 \| 停止删除文件、撤销网络调用 \|
#903	\| SafePoint \| 到安全点处理 \| 修改目标、切换策略 \|
#904	\| Deferred \| 延迟生效 \| 更新偏好、补充背景信息 \|
#905	\| Informational \| 不改变执行 \| 查询状态、请求解释 \|
#906
#907	```python
#908	class InterruptClass(Enum):
#909	IMMEDIATE = "immediate"
#910	SAFE_POINT = "safe_point"
#911	DEFERRED = "deferred"
#912	INFORMATIONAL = "informational"
#913	```
#914
#915	所有立即中断都必须进入 audit log，并触发 checkpoint 或状态 dump。
#916
#917	---
#918
#919	## 3.5 Capability System
#920
#921	## 3.5.1 设计目标
#922
#923	Capability System 是安全核心。
#924
#925	它控制：
#926
#927	- 对象访问；
#928	- 文件系统访问；
#929	- 网络访问；
#930	- shell 执行；
#931	- 人类访问；
#932	- skill loading；
#933	- tool calling；
#934	- tool registration；
#935	- fork/exec；
#936	- memory write；
#937	- external side effects。
#938
#939	### 3.5.2 Capability
#940
#941	```python
#942	@dataclass(frozen=True)
#943	class Capability:
#944	cap_id: CapabilityID
#945	subject: ActorRef
#946	resource: ResourceRef
#947	rights: set[Right]
#948	constraints: list[CapabilityConstraint]
#949	issued_by: ActorRef
#950	issued_at: Timestamp
#951	expires_at: Timestamp \| None
#952	delegable: bool
#953	revocable: bool
#954	```
#955
#956	### 3.5.3 Rights
#957
#958	```python
#959	class Right(Enum):
#960	READ = "read"
#961	WRITE = "write"
#962	EXECUTE = "execute"
#963	DELETE = "delete"
#964	LIST = "list"
#965	NETWORK = "network"
#966	SHELL = "shell"
#967	HUMAN_QUERY = "human_query"
#968	HUMAN_INTERRUPT = "human_interrupt"
#969	LOAD_SKILL = "load_skill"
#970	REGISTER_TOOL = "register_tool"
#971	CALL_TOOL = "call_tool"
#972	SPAWN_PROCESS = "spawn_process"
#973	GRANT_CAPABILITY = "grant_capability"
#974	REVOKE_CAPABILITY = "revoke_capability"
#975	PERSIST_MEMORY = "persist_memory"
#976	EXTERNAL_SIDE_EFFECT = "external_side_effect"
#977	```
#978
#979	### 3.5.4 Capability API
#980
#981	```python
#982	class CapabilityAPI:
#983	def request(
#984	self,
#985	pid: PID,
#986	resource: ResourceRef,
#987	rights: set[Right],
#988	reason: str,
#989	duration: Duration \| None = None,
#990	) -> CapabilityDecision: ...
#991
#992	def grant(
#993	self,
#994	issuer: ActorRef,
#995	subject: ActorRef,
#996	resource: ResourceRef,
#997	rights: set[Right],
#998	constraints: list[CapabilityConstraint] \| None = None,
#999	duration: Duration \| None = None,
#1000	) -> Capability: ...
#1001
#1002	def revoke(self, issuer: ActorRef, cap_id: CapabilityID, reason: str) -> None: ...
#1003
#1004	def check(
#1005	self,
#1006	subject: ActorRef,
#1007	resource: ResourceRef,
#1008	right: Right,
#1009	context: dict \| None = None,
#1010	) -> bool: ...
#1011
#1012	def delegate(
#1013	self,
#1014	pid: PID,
#1015	cap_id: CapabilityID,
#1016	target: ActorRef,
#1017	attenuation: CapabilityAttenuation,
#1018	) -> Capability: ...
#1019
#1020	def attenuate(
#1021	self,
#1022	cap: Capability,
#1023	attenuation: CapabilityAttenuation,
#1024	) -> Capability: ...
#1025	```
#1026
#1027	### 3.5.5 fork 时的 capability 继承
#1028
#1029	默认规则：
#1030
#1031	```text
#1032	子进程不自动继承父进程全部 capability。
#1033	fork 必须显式指定 capability inheritance policy。
#1034	所有 inherited capability 默认 attenuate。
#1035	高风险 capability 不可自动继承。
#1036	```
#1037
#1038	```python
#1039	class CapabilityInheritancePolicy(Enum):
#1040	NONE = "none"
#1041	READ_ONLY = "read_only"
#1042	EXPLICIT = "explicit"
#1043	ATTENUATED = "attenuated"
#1044	FULL_TRUSTED = "full_trusted"
#1045	```
#1046
#1047	MVP 默认使用 `EXPLICIT` 或 `ATTENUATED`。
#1048
#1049	### 3.5.6 高风险 capability
#1050
#1051	以下 capability 默认需要人类授权或管理员策略授权：
#1052
#1053	- 任意网络访问；
#1054	- shell 写操作；
#1055	- 删除文件；
#1056	- 修改 git history；
#1057	- 发送邮件；
#1058	- 注册持久工具；
#1059	- 加载未签名 skill；
#1060	- 写入长期记忆；
#1061	- 访问凭据；
#1062	- fork 大量子进程；
#1063	- exec 到未信任镜像；
#1064	- 访问敏感对象。
#1065
#1066	---
#1067
#1068	## 3.6 Skills / Tools Layer
#1069
#1070	## 3.6.1 分层定位
#1071
#1072	Skills / Tools Layer 是 Agent personality 与 Agent LibOS 之间的 LLM-facing capability layer。
#1073
#1074	它不应该被理解为 Host Runtime 的一部分，也不应该直接等同于 libOS kernel ABI。它的职责是把底层原语包装成模型可调用的工具、技能和组合动作。
#1075
#1076	这一层包括两类能力：
#1077
#1078	- Skill：改变 Agent 如何理解、计划、判断、压缩上下文和使用工具；
#1079	- Tool：暴露一个可调用动作，可能访问外部环境或触发 libOS 原语组合。
#1080
#1081	底层 libOS 原语应该保持小而稳定；Skills / Tools Layer 可以快速演化、按领域扩展、按任务加载。
#1082
#1083	## 3.6.2 Skill 定义
#1084
#1085	Skill 是动态链接到 Agent Process 的能力模块。
#1086
#1087	Skill 不应直接等同于 Tool。
#1088
#1089	区别：
#1090
#1091	\| 概念 \| 类比 \| 作用 \|
#1092	\|------------\|----------------------------------\|-----------------------\|
#1093	\| Tool \| function call / external service \| 访问外部世界，可能有副作用 \|
#1094	\| Skill \| dynamic library \| 增强 Agent 内部能力、策略和领域知识 \|
#1095	\| AgentImage \| executable image \| 定义进程执行身份和默认行为 \|
#1096	\| Subagent \| child process \| 隔离执行子任务 \|
#1097
#1098	### 3.6.3 SkillObject
#1099
#1100	```python
#1101	@dataclass(frozen=True)
#1102	class SkillObject:
#1103	skill_id: SkillID
#1104	name: str
#1105	version: str
#1106	description: str
#1107	instructions: str
#1108	examples: list[SkillExample]
#1109	resources: list[ObjectHandle]
#1110	scripts: list[ScriptRef]
#1111	required_capabilities: list[CapabilityRequirement]
#1112	compatible_images: list[AgentImageID]
#1113	metadata: dict
#1114	signature: Signature \| None
#1115	```
#1116
#1117	### 3.6.4 Skill API
#1118
#1119	```python
#1120	class SkillAPI:
#1121	def discover(
#1122	self,
#1123	pid: PID,
#1124	query: SkillQuery,
#1125	) -> list[SkillRef]: ...
#1126
#1127	def load(
#1128	self,
#1129	pid: PID,
#1130	skill: SkillRef,
#1131	mode: SkillLoadMode = SkillLoadMode.LAZY,
#1132	) -> SkillHandle: ...
#1133
#1134	def unload(self, pid: PID, handle: SkillHandle) -> None: ...
#1135
#1136	def resolve(
#1137	self,
#1138	pid: PID,
#1139	symbol: str,
#1140	) -> SkillSymbol \| None: ...
#1141
#1142	def verify(self, skill: SkillRef) -> VerificationResult: ...
#1143
#1144	def pin_version(self, pid: PID, skill: SkillRef, version: str) -> None: ...
#1145	```
#1146
#1147	### 3.6.5 Skill 加载语义
#1148
#1149	Skill load 必须经过：
#1150
#1151	- schema/version compatibility check；
#1152	- signature/provenance check；
#1153	- capability requirement check；
#1154	- prompt injection scan；
#1155	- resource access check；
#1156	- audit log。
#1157
#1158	默认使用 lazy loading：
#1159
#1160	```text
#1161	Skill 元数据先进入上下文；
#1162	完整 instructions/examples/scripts 仅在需要时 materialize。
#1163	```
#1164
#1165	---
#1166
#1167	## 3.7 Tool Broker 与 JIT Tool
#1168
#1169	## 3.7.1 设计目标
#1170
#1171	Tool Broker 负责管理所有工具调用和工具注册。
#1172
#1173	Agent 不应直接获得任意代码执行权。它可以提出工具候选，但必须由 Tool Broker 进行验证、构建、测试、签名和授权。
#1174
#1175	需要注意：Tool Broker 属于 libOS/runtime 的安全边界；而具体暴露给 LLM 的 tool/action 属于 Skills / Tools Layer。二者关系为：
#1176
#1177	```text
#1178	ToolBroker: build / verify / sandbox / register / revoke
#1179	SkillsToolsLayer: describe / wrap / compose / expose to LLM
#1180	```
#1181
#1182	因此，工具注册完成后，还需要生成 LLM-facing wrapper，包括名称、说明、schema、示例、权限提示、失败模式和使用策略。
#1183
#1184	### 3.7.2 ToolSpec
#1185
#1186	```python
#1187	@dataclass(frozen=True)
#1188	class ToolSpec:
#1189	name: str
#1190	description: str
#1191	input_schema: dict
#1192	output_schema: dict
#1193	side_effects: list[SideEffect]
#1194	required_capabilities: list[CapabilityRequirement]
#1195	timeout: Duration
#1196	resource_limits: ResourceLimits
#1197	deterministic: bool
#1198	idempotent: bool
#1199	```
#1200
#1201	### 3.7.3 ToolCandidateObject
#1202
#1203	```python
#1204	@dataclass(frozen=True)
#1205	class ToolCandidateObject:
#1206	candidate_id: ToolCandidateID
#1207	spec: ToolSpec
#1208	source_code: str
#1209	tests: list[ToolTest]
#1210	build_config: BuildConfig
#1211	requested_capabilities: list[CapabilityRequirement]
#1212	created_by: PID
#1213	provenance: Provenance
#1214	```
#1215
#1216	### 3.7.4 ToolHandle
#1217
#1218	```python
#1219	@dataclass(frozen=True)
#1220	class ToolHandle:
#1221	tool_id: ToolID
#1222	version: str
#1223	rights: set[Right]
#1224	capability_id: CapabilityID
#1225	sandbox_profile: SandboxProfile
#1226	expires_at: Timestamp \| None
#1227	```
#1228
#1229	### 3.7.5 Tool API
#1230
#1231	```python
#1232	class ToolAPI:
#1233	def call(
#1234	self,
#1235	pid: PID,
#1236	tool: ToolHandle,
#1237	args: dict,
#1238	timeout: Duration \| None = None,
#1239	) -> ToolCallID: ...
#1240
#1241	def get_result(self, pid: PID, call_id: ToolCallID) -> ToolResultObject: ...
#1242
#1243	def propose(
#1244	self,
#1245	pid: PID,
#1246	spec: ToolSpec,
#1247	source_code: str,
#1248	tests: list[ToolTest],
#1249	requested_capabilities: list[CapabilityRequirement],
#1250	) -> ToolCandidateID: ...
#1251
#1252	def validate(self, candidate: ToolCandidateID) -> ValidationResult: ...
#1253
#1254	def register(
#1255	self,
#1256	approver: ActorRef,
#1257	candidate: ToolCandidateID,
#1258	scope: ToolScope,
#1259	) -> ToolHandle: ...
#1260
#1261	def revoke(self, issuer: ActorRef, tool_id: ToolID, reason: str) -> None: ...
#1262	```
#1263
#1264	### 3.7.6 JIT Tool 注册流水线
#1265
#1266	```text
#1267	1. Agent 创建 ToolCandidateObject
#1268	2. ToolBroker 进行 schema 检查
#1269	3. Sandbox 构建环境
#1270	4. 执行静态分析
#1271	5. 执行单元测试
#1272	6. 执行资源限制测试
#1273	7. 分析 requested capabilities
#1274	8. PolicyEngine 判断是否需要 human approval
#1275	9. HumanObject 批准/拒绝/修改权限
#1276	10. ToolRegistry 签名并注册
#1277	11. Agent 获得受限 ToolHandle
#1278	12. AuditManager 记录完整链路
#1279	```
#1280
#1281	### 3.7.7 Tool Scope
#1282
#1283	```python
#1284	class ToolScope(Enum):
#1285	EPHEMERAL_PROCESS = "ephemeral_process"
#1286	TASK_LOCAL = "task_local"
#1287	USER_LOCAL = "user_local"
#1288	PROJECT_LOCAL = "project_local"
#1289	GLOBAL_SIGNED = "global_signed"
#1290	```
#1291
#1292	MVP 只允许：
#1293
#1294	- `EPHEMERAL_PROCESS`；
#1295	- `TASK_LOCAL`。
#1296
#1297	`PROJECT_LOCAL` 和 `GLOBAL_SIGNED` 需要更严格治理。
#1298
#1299	---
#1300
#1301	## 3.8 HumanObject
#1302
#1303	## 3.8.1 定义
#1304
#1305	HumanObject 是外部对象、权限持有者和中断源。
#1306
#1307	它不是普通工具。
#1308
#1309	HumanObject 支持：
#1310
#1311	- 被 Agent query；
#1312	- 回复 approval/rejection/edit；
#1313	- 主动 interrupt Agent；
#1314	- grant/revoke capability；
#1315	- inspect state；
#1316	- override goal；
#1317	- request explanation。
#1318
#1319	### 3.8.2 HumanObject 数据模型
#1320
#1321	```python
#1322	@dataclass
#1323	class HumanObject:
#1324	human_id: HumanID
#1325	display_name: str
#1326	roles: list[HumanRole]
#1327	authority: AuthorityProfile
#1328	contact_channels: list[ContactChannel]
#1329	availability_policy: AvailabilityPolicy
#1330	interruption_cost: InterruptionCostModel
#1331	preferences_ref: ObjectHandle \| None
#1332	```
#1333
#1334	### 3.8.3 HumanRequest
#1335
#1336	```python
#1337	@dataclass(frozen=True)
#1338	class HumanRequest:
#1339	request_id: HumanRequestID
#1340	pid: PID
#1341	type: HumanRequestType
#1342	question: str
#1343	context_objects: list[ObjectHandle]
#1344	options: list[HumanOption] \| None
#1345	expected_schema: dict \| None
#1346	default_action: HumanDefaultAction \| None
#1347	deadline: Timestamp \| None
#1348	blocking: bool
#1349	risk_level: RiskLevel
#1350	created_at: Timestamp
#1351	```
#1352
#1353	```python
#1354	class HumanRequestType(Enum):
#1355	CLARIFICATION = "clarification"
#1356	APPROVAL = "approval"
#1357	PREFERENCE = "preference"
#1358	AUTHORIZATION = "authorization"
#1359	CONSTRAINT_UPDATE = "constraint_update"
#1360	STATUS_REVIEW = "status_review"
#1361	EXCEPTION_HANDLING = "exception_handling"
#1362	```
#1363
#1364	### 3.8.4 Human API
#1365
#1366	```python
#1367	class HumanAPI:
#1368	def query(
#1369	self,
#1370	pid: PID,
#1371	human: HumanID,
#1372	request: HumanRequest,
#1373	) -> HumanRequestID: ...
#1374
#1375	def receive_response(
#1376	self,
#1377	request_id: HumanRequestID,
#1378	response: HumanResponse,
#1379	) -> None: ...
#1380
#1381	def interrupt(
#1382	self,
#1383	human: HumanID,
#1384	target_pid: PID,
#1385	signal: ProcessSignal,
#1386	payload: dict \| None = None,
#1387	) -> EventID: ...
#1388
#1389	def inspect(
#1390	self,
#1391	human: HumanID,
#1392	pid: PID,
#1393	scope: InspectScope,
#1394	) -> InspectionResult: ...
#1395
#1396	def approve(
#1397	self,
#1398	human: HumanID,
#1399	request_id: HumanRequestID,
#1400	decision: ApprovalDecision,
#1401	) -> None: ...
#1402
#1403	def grant_capability(
#1404	self,
#1405	human: HumanID,
#1406	pid: PID,
#1407	resource: ResourceRef,
#1408	rights: set[Right],
#1409	constraints: list[CapabilityConstraint],
#1410	) -> Capability: ...
#1411
#1412	def revoke_capability(
#1413	self,
#1414	human: HumanID,
#1415	cap_id: CapabilityID,
#1416	reason: str,
#1417	) -> None: ...
#1418	```
#1419
#1420	### 3.8.5 Human Interrupt 类型
#1421
#1422	```python
#1423	class HumanSignal(Enum):
#1424	PAUSE = "pause"
#1425	RESUME = "resume"
#1426	CANCEL = "cancel"
#1427	CHANGE_GOAL = "change_goal"
#1428	ADD_CONSTRAINT = "add_constraint"
#1429	REVOKE_CAPABILITY = "revoke_capability"
#1430	REQUEST_STATUS = "request_status"
#1431	REQUEST_EXPLANATION = "request_explanation"
#1432	ROLLBACK = "rollback"
#1433	APPROVE_PENDING = "approve_pending"
#1434	REJECT_PENDING = "reject_pending"
#1435	```
#1436
#1437	---
#1438
#1439	## 3.9 Checkpoint 与 Rollback
#1440
#1441	## 3.9.1 Checkpoint 内容
#1442
#1443	Agent checkpoint 不保存字节级内存，而是保存对象图 root 和运行状态引用。
#1444
#1445	```python
#1446	@dataclass(frozen=True)
#1447	class Checkpoint:
#1448	checkpoint_id: CheckpointID
#1449	pid: PID
#1450	image: AgentImageRef
#1451	process_state: ObjectHandle
#1452	goal: ObjectHandle
#1453	memory_view: MemoryView
#1454	capability_snapshot: CapabilitySnapshot
#1455	loaded_skills: list[SkillHandle]
#1456	tool_table: list[ToolHandle]
#1457	event_cursor: EventCursor
#1458	pending_requests: list[HumanRequestID \| ToolCallID]
#1459	created_at: Timestamp
#1460	reason: str
#1461	```
#1462
#1463	### 3.9.2 Checkpoint API
#1464
#1465	```python
#1466	class CheckpointAPI:
#1467	def create(self, pid: PID, reason: str) -> CheckpointID: ...
#1468
#1469	def restore(self, pid: PID, checkpoint: CheckpointID) -> None: ...
#1470
#1471	def rollback(
#1472	self,
#1473	pid: PID,
#1474	checkpoint: CheckpointID,
#1475	rollback_policy: RollbackPolicy,
#1476	) -> RollbackResult: ...
#1477
#1478	def diff(self, a: CheckpointID, b: CheckpointID) -> CheckpointDiff: ...
#1479
#1480	def list(self, pid: PID) -> list[CheckpointSummary]: ...
#1481	```
#1482
#1483	### 3.9.3 Rollback 限制
#1484
#1485	不是所有外部副作用都可回滚。
#1486
#1487	必须区分：
#1488
#1489	- object memory rollback；
#1490	- process state rollback；
#1491	- tool table rollback；
#1492	- filesystem diff rollback；
#1493	- external side-effect compensation。
#1494
#1495	例如，发送邮件不可真正撤销，只能记录 compensation action。
#1496
#1497	---
#1498
#1499	## 3.10 Primitive Managers 与 Resource Provider Substrate
#1500
#1501	## 3.10.1 Primitive 类型
#1502
#1503	文件系统不是根抽象，而是 libOS primitive 之一。Primitive 负责 libOS 语义，Resource Provider Substrate 负责真实宿主资源访问。
#1504
#1505	```text
#1506	Primitive Managers:
#1507	FilesystemAdapter
#1508	ShellAdapter
#1509	ClockPrimitive
#1510	HumanObjectManager
#1511	ImageRegistryPrimitive
#1512	ProcessManager
#1513	ObjectMemoryManager
#1514	Future Browser/Git/Database/IDE/Calendar/Mail/Search primitives
#1515	```
#1516
#1517	Primitive 不应直接等同于底层 Host OS 调用。Primitive 负责 libOS 语义，例如 capability 检查、人类授权、审计和事件；
#1518	真正的资源访问应委托给可替换的 Resource Provider Substrate：
#1519
#1520	```python
#1521	class ResourceProviderSubstrate:
#1522	filesystem: FilesystemProvider
#1523	clock: ClockProvider
#1524	shell: ShellProvider
#1525	human: HumanProvider
#1526	```
#1527
#1528	MVP 默认实现可以是本地 host-backed provider；后续可以替换为容器、远程执行环境、WASM sandbox、云对象存储或其它
#1529	Resource Provider Substrate，而不改变 Agent 可见工具、process capability 模型和 audit/event 语义。
#1530	HumanObjectManager 仍负责请求队列、审批状态机、process wakeup、capability/audit/event 语义；终端或 UI 的实际读写由
#1531	HumanProvider 承担。
#1532
#1533	### 3.10.2 ExternalObjectRef
#1534
#1535	```python
#1536	@dataclass(frozen=True)
#1537	class ExternalObjectRef:
#1538	adapter: str
#1539	external_id: str
#1540	type: str
#1541	metadata: dict
#1542	```
#1543
#1544	外部实体需要进入 Object Memory 时，通过 ExternalRefObject 保存可审计引用和快照，而不是绕过 primitive/provider 边界：
#1545
#1546	```python
#1547	@dataclass(frozen=True)
#1548	class ExternalRefPayload:
#1549	ref: ExternalObjectRef
#1550	snapshot: ObjectHandle \| None
#1551	last_observed_at: Timestamp
#1552	consistency: ConsistencyModel
#1553	```
#1554
#1555	---
#1556
#1557	## 4. 调度与执行模型
#1558
#1559	## 4.1 Scheduler 目标
#1560
#1561	Scheduler 负责决定哪个 Agent Process 可以执行、执行多久、何时暂停、何时处理事件。
#1562
#1563	调度依据：
#1564
#1565	- process status；
#1566	- priority；
#1567	- deadline；
#1568	- resource budget；
#1569	- waiting events；
#1570	- human availability；
#1571	- risk level；
#1572	- pending approvals；
#1573	- child process dependencies。
#1574
#1575	## 4.2 Execution Quantum
#1576
#1577	Agent Process 每次执行一个 quantum。若该进程消息队列中存在 unread interrupt message，runtime 必须在实际 tool 调用前通知进程并抢占非消息读取类 tool；若存在 unread normal message，runtime 应在当前 tool 调用结束后通知进程。消息本体通过显式 `read_process_messages` / `process.read_messages` 查看，读取默认 ack，避免把队列语义退化成不可控 prompt 文本。若进程需要等待 IPC，可调用 `receive_process_messages` / `process.receive_messages` 并按 kind、sender、channel、correlation_id、reply_to 或 message_ids 做选择性匹配；无匹配消息时进程进入 `WAITING_EVENT`，匹配消息到达后由消息队列 manager 唤醒并恢复原 action/syscall。人类主动输入也应由 HumanObject primitive 作为 `human:<name>` sender 投递到同一进程 mailbox，包括普通消息和 interrupt；不得直接拼接进 prompt 或绕过消息队列。
#1578
#1579	一个 quantum 可能包括：
#1580
#1581	- materialize context；
#1582	- call LLM；
#1583	- parse action；
#1584	- validate action；
#1585	- dispatch one action；
#1586	- update state；
#1587	- checkpoint if needed。
#1588
#1589	MVP 中建议每个 quantum 最多产生一个外部副作用 action。
#1590
#1591	## 4.3 Safe Point
#1592
#1593	Safe Point 是可处理中断、创建 checkpoint、合并子任务和接受人类修改的位置。
#1594
#1595	Safe Point 发生在：
#1596
#1597	- LLM action 之前；
#1598	- tool call 之前；
#1599	- tool result 之后；
#1600	- memory merge 前；
#1601	- JIT tool register 前；
#1602	- high-risk side effect 前；
#1603	- child process join 后；
#1604	- human response 后。
#1605
#1606	## 4.4 Blocking vs Non-blocking Human Requests
#1607
#1608	Human request 分两类：
#1609
#1610	- blocking：没有回复不能继续；
#1611	- non-blocking：Agent 可继续做低风险替代任务。
#1612
#1613	默认规则：
#1614
#1615	```text
#1616	审批类请求 blocking。
#1617	偏好类请求可 non-blocking。
#1618	状态询问不阻塞。
#1619	高风险授权必须 blocking。
#1620	```
#1621
#1622	---
#1623
#1624	## 5. 安全模型
#1625
#1626	## 5.1 威胁模型
#1627
#1628	需要防范：
#1629
#1630	1. Agent 误操作；
#1631	2. prompt injection；
#1632	3. tool output injection；
#1633	4. skill poisoning；
#1634	5. JIT tool 恶意或错误代码；
#1635	6. capability bypass；
#1636	7. fork bomb；
#1637	8. resource exhaustion；
#1638	9. credential leakage；
#1639	10. unsafe external side effects；
#1640	11. human approval spoofing；
#1641	12. audit log tampering。
#1642
#1643	## 5.2 安全边界
#1644
#1645	### 5.2.1 Agent Process 边界
#1646
#1647	Agent Process 不能直接访问宿主资源。所有访问必须经由 capability。
#1648
#1649	### 5.2.2 Tool Sandbox 边界
#1650
#1651	JIT tool 和高风险工具必须运行在 sandbox 中。
#1652
#1653	Sandbox 需要限制：
#1654
#1655	- filesystem；
#1656	- network；
#1657	- environment variables；
#1658	- CPU；
#1659	- memory；
#1660	- wall time；
#1661	- subprocess；
#1662	- credentials。
#1663
#1664	### 5.2.3 Skill 边界
#1665
#1666	Skill 是能力模块，不应默认获得外部副作用权限。
#1667
#1668	Skill 中包含的脚本也必须通过 ToolBroker 或 Sandbox 执行。
#1669
#1670	### 5.2.4 Human Authority 边界
#1671
#1672	不同 human role 拥有不同授权能力。
#1673
#1674	```python
#1675	class HumanRole(Enum):
#1676	OWNER = "owner"
#1677	DEVELOPER = "developer"
#1678	REVIEWER = "reviewer"
#1679	OPERATOR = "operator"
#1680	OBSERVER = "observer"
#1681	```
#1682
#1683	例如：
#1684
#1685	- OWNER 可以 grant/revoke 高风险 capability；
#1686	- REVIEWER 可以 approve code patch；
#1687	- OBSERVER 只能 inspect status。
#1688
#1689	## 5.3 Policy Engine
#1690
#1691	PolicyEngine 接收 action proposal，返回 decision。
#1692
#1693	```python
#1694	class PolicyDecision(Enum):
#1695	ALLOW = "allow"
#1696	DENY = "deny"
#1697	REQUIRE_HUMAN_APPROVAL = "require_human_approval"
#1698	REQUIRE_SANDBOX = "require_sandbox"
#1699	REQUIRE_CHECKPOINT = "require_checkpoint"
#1700	REQUIRE_CAPABILITY_ATTENUATION = "require_capability_attenuation"
#1701	```
#1702
#1703	```python
#1704	class PolicyEngine:
#1705	def evaluate_action(
#1706	self,
#1707	pid: PID,
#1708	action: ActionProposal,
#1709	context: PolicyContext,
#1710	) -> PolicyDecisionBundle: ...
#1711	```
#1712
#1713	## 5.4 默认安全规则
#1714
#1715	1. 默认无网络；
#1716	2. 默认无 shell；
#1717	3. 默认不能写长期记忆；
#1718	4. 默认不能注册持久工具；
#1719	5. 默认不能加载未签名 skill；
#1720	6. fork 默认权限收缩；
#1721	7. exec 不提升权限；
#1722	8. JIT tool 默认 ephemeral；
#1723	9. 高风险操作前自动 checkpoint；
#1724	10. 所有人类授权必须进入 audit log。
#1725
#1726	---
#1727
#1728	## 6. 审计与可观测性
#1729
#1730	## 6.1 Audit Record
#1731
#1732	```python
#1733	@dataclass(frozen=True)
#1734	class AuditRecord:
#1735	record_id: AuditID
#1736	timestamp: Timestamp
#1737	actor: ActorRef
#1738	action: str
#1739	target: ResourceRef \| None
#1740	input_refs: list[OID]
#1741	output_refs: list[OID]
#1742	capability_refs: list[CapabilityID]
#1743	decision: str \| None
#1744	policy_decision: PolicyDecisionBundle \| None
#1745	correlation_id: CorrelationID \| None
#1746	parent_record_id: AuditID \| None
#1747	```
#1748
#1749	## 6.2 必须审计的操作
#1750
#1751	- process fork/exec/exit/kill；
#1752	- capability grant/revoke/request/deny；
#1753	- skill load/unload；
#1754	- tool call；
#1755	- tool propose/register/revoke；
#1756	- human query/response/approval/interrupt；
#1757	- external side effect；
#1758	- memory persistent write；
#1759	- checkpoint/rollback；
#1760	- policy violation；
#1761	- sandbox failure。
#1762
#1763	## 6.3 Trace 查询
#1764
#1765	支持回答：
#1766
#1767	- 某个修改为什么发生？
#1768	- 哪个人批准了这个操作？
#1769	- 某个子 Agent 继承了哪些 capability？
#1770	- 某个 JIT tool 是谁创建的，测试结果如何？
#1771	- 某个对象被哪些进程读取过？
#1772	- rollback 会影响哪些对象？
#1773
#1774	---
#1775
#1776	## 7. 最小可行版本 MVP
#1777
#1778	## 7.1 MVP 目标
#1779
#1780	第一版不要实现完整 Agent OS。目标是验证核心抽象：
#1781
#1782	1. Agent Process 可运行；
#1783	2. Object Memory 可创建、查询、materialize；
#1784	3. capability 可以限制工具调用；
#1785	4. human interrupt/approval 可暂停恢复；
#1786	5. JIT tool 可在 sandbox 中生成、测试、注册为 ephemeral tool；
#1787	6. fork worker 子进程可执行封闭任务；
#1788	7. audit log 可追踪关键动作。
#1789
#1790	## 7.2 MVP 模块清单
#1791
#1792	### 必须实现
#1793
#1794	- ProcessManager；
#1795	- EventBus；
#1796	- ObjectMemoryManager；
#1797	- ContextMaterializer；
#1798	- CapabilityManager；
#1799	- ToolBroker；
#1800	- HumanObjectManager；
#1801	- AuditManager；
#1802	- SimpleScheduler；
#1803	- SQLite/Postgres-backed store；
#1804	- Docker/Firecracker-like sandbox abstraction，初版可用 Docker；
#1805	- CLI/Web debug console。
#1806
#1807	### 暂不实现
#1808
#1809	- 完整多租户；
#1810	- 分布式调度；
#1811	- 复杂 actor runtime；
#1812	- 全局 skill marketplace；
#1813	- 持久化全局 JIT tool registry；
#1814	- 自动长期记忆优化；
#1815	- 复杂 rollback compensation；
#1816	- formal verification。
#1817
#1818	## 7.3 MVP API 原语
#1819
#1820	```python
#1821	# process
#1822	fork(goal, memory_view, capabilities) -> PID
#1823	exec(pid, image) -> None
#1824	signal(pid, signal) -> None
#1825	wait(pid) -> ProcessResult
#1826
#1827	# memory
#1828	create_object(type, payload) -> ObjectHandle
#1829	get_object(handle) -> AgentObject
#1830	link_objects(src, relation, dst) -> None
#1831	query_objects(query) -> list[ObjectHandle]
#1832	create_view(roots) -> MemoryView
#1833	materialize_context(view, budget) -> MaterializedContext
#1834
#1835	# capability
#1836	request(resource, rights, reason) -> Decision
#1837	grant(subject, resource, rights) -> Capability
#1838	revoke(capability) -> None
#1839	check(subject, resource, right) -> bool
#1840
#1841	# human
#1842	query(human, request) -> HumanRequestID
#1843	interrupt(pid, signal) -> EventID
#1844	approve(request_id, decision) -> None
#1845
#1846	# tool
#1847	call(tool_handle, args) -> ToolCallID
#1848	propose_tool(spec, code, tests) -> ToolCandidateID
#1849	validate_tool(candidate) -> ValidationResult
#1850	register_tool(candidate) -> ToolHandle
#1851
#1852	# checkpoint
#1853	checkpoint(pid, reason) -> CheckpointID
#1854	rollback(pid, checkpoint) -> RollbackResult
#1855	```
#1856
#1857	## 7.4 MVP 参考任务
#1858
#1859	选择一个 coding-agent demo：
#1860
#1861	```text
#1862	目标：修复一个小型 Python/Rust 项目的 failing tests。
#1863	```
#1864
#1865	流程：
#1866
#1867	1. Root Agent 创建 task object；
#1868	2. 读取 repo summary、test log；
#1869	3. fork worker 分析错误日志；
#1870	4. worker 返回 ErrorTrace object；
#1871	5. Root Agent 生成 patch；
#1872	6. 调用 test tool；
#1873	7. 如需专门解析日志，propose JIT parser tool；
#1874	8. ToolBroker sandbox 测试 parser；
#1875	9. 注册 ephemeral parser；
#1876	10. Agent 使用 parser 辅助调试；
#1877	11. 高风险修改前请求 human approval；
#1878	12. human approve；
#1879	13. 应用 patch；
#1880	14. 运行测试；
#1881	15. 生成 audit trace 和 final report。
#1882
#1883	这个 demo 可以覆盖 process、memory、tool、human、capability、audit 的核心链路。
#1884
#1885	---
#1886
#1887	## 8. 目录结构建议
#1888
#1889	```text
#1890	agent_libos/
#1891	skills_tools/
#1892	skill_registry.py
#1893	tool_registry.py
#1894	tool_bundle.py
#1895	action_schema.py
#1896	wrappers.py
#1897	macros.py
#1898	package_loader.py
#1899
#1900	runtime/
#1901	process_manager.py
#1902	scheduler.py
#1903	event_bus.py
#1904	audit_manager.py
#1905	checkpoint_manager.py
#1906
#1907	memory/
#1908	object_store.py
#1909	object_graph.py
#1910	memory_view.py
#1911	materializer.py
#1912	schemas.py
#1913
#1914	capability/
#1915	manager.py
#1916	policy.py
#1917	rights.py
#1918	constraints.py
#1919
#1920	skills/
#1921	linker.py
#1922	registry.py
#1923	verifier.py
#1924	schema.py
#1925
#1926	tools/
#1927	broker.py
#1928	registry.py
#1929	sandbox.py
#1930	validator.py
#1931	schemas.py
#1932
#1933	human/
#1934	manager.py
#1935	requests.py
#1936	interrupts.py
#1937	ui_adapter.py
#1938
#1939	primitives/
#1940	filesystem.py
#1941	shell.py
#1942	git.py
#1943	browser.py
#1944	database.py
#1945
#1946	images/
#1947	base_agent.py
#1948	coding_agent.py
#1949	toolmaker_agent.py
#1950	review_agent.py
#1951
#1952	llm/
#1953	client.py
#1954	action_parser.py
#1955	context_protocol.py
#1956
#1957	storage/
#1958	postgres.py
#1959	sqlite.py
#1960	blob_store.py
#1961
#1962	api/
#1963	python_sdk.py
#1964	server.py
#1965	cli.py
#1966
#1967	tests/
#1968	unit/
#1969	integration/
#1970	sandbox/
#1971	security/
#1972	```
#1973
#1974	---
#1975
#1976	## 9. 数据库与存储建议
#1977
#1978	## 9.1 存储层
#1979
#1980	MVP 可使用：
#1981
#1982	- Postgres：metadata、objects、links、events、capabilities、audit；
#1983	- S3/MinIO/local blob store：大 payload、tool artifacts、logs；
#1984	- Redis/NATS：事件队列，MVP 可先用 Postgres queue；
#1985	- Vector DB：对象 embedding，MVP 可先用 pgvector。
#1986
#1987	## 9.2 表结构草案
#1988
#1989	```sql
#1990	CREATE TABLE objects
#1991	(
#1992	oid TEXT PRIMARY KEY,
#1993	type TEXT NOT NULL,
#1994	schema_version TEXT NOT NULL,
#1995	payload_ref TEXT,
#1996	payload_json JSONB,
#1997	metadata JSONB NOT NULL,
#1998	provenance JSONB NOT NULL,
#1999	version INTEGER NOT NULL,
#2000	immutable BOOLEAN NOT NULL,
#2001	created_by TEXT NOT NULL,
#2002	created_at TIMESTAMP NOT NULL,
#2003	updated_at TIMESTAMP NOT NULL
#2004	);
#2005
#2006	CREATE TABLE object_links
#2007	(
#2008	id TEXT PRIMARY KEY,
#2009	src_oid TEXT NOT NULL,
#2010	relation TEXT NOT NULL,
#2011	dst_oid TEXT NOT NULL,
#2012	metadata JSONB,
#2013	created_by TEXT NOT NULL,
#2014	created_at TIMESTAMP NOT NULL
#2015	);
#2016
#2017	CREATE TABLE processes
#2018	(
#2019	pid TEXT PRIMARY KEY,
#2020	parent_pid TEXT,
#2021	image_id TEXT NOT NULL,
#2022	status TEXT NOT NULL,
#2023	goal_oid TEXT,
#2024	memory_view_id TEXT,
#2025	capabilities JSONB,
#2026	loaded_skills JSONB,
#2027	tool_table JSONB,
#2028	event_cursor TEXT,
#2029	created_at TIMESTAMP NOT NULL,
#2030	updated_at TIMESTAMP NOT NULL
#2031	);
#2032
#2033	CREATE TABLE events
#2034	(
#2035	event_id TEXT PRIMARY KEY,
#2036	type TEXT NOT NULL,
#2037	source TEXT NOT NULL,
#2038	target TEXT,
#2039	payload JSONB NOT NULL,
#2040	priority INTEGER NOT NULL,
#2041	created_at TIMESTAMP NOT NULL,
#2042	correlation_id TEXT,
#2043	causality JSONB
#2044	);
#2045
#2046	CREATE TABLE capabilities
#2047	(
#2048	cap_id TEXT PRIMARY KEY,
#2049	subject TEXT NOT NULL,
#2050	resource TEXT NOT NULL,
#2051	rights JSONB NOT NULL,
#2052	constraints JSONB,
#2053	issued_by TEXT NOT NULL,
#2054	issued_at TIMESTAMP NOT NULL,
#2055	expires_at TIMESTAMP,
#2056	delegable BOOLEAN NOT NULL,
#2057	revocable BOOLEAN NOT NULL,
#2058	revoked BOOLEAN NOT NULL DEFAULT FALSE
#2059	);
#2060
#2061	CREATE TABLE audit_records
#2062	(
#2063	record_id TEXT PRIMARY KEY,
#2064	timestamp TIMESTAMP NOT NULL,
#2065	actor TEXT NOT NULL,
#2066	action TEXT NOT NULL,
#2067	target TEXT,
#2068	input_refs JSONB,
#2069	output_refs JSONB,
#2070	capability_refs JSONB,
#2071	decision JSONB,
#2072	correlation_id TEXT,
#2073	parent_record_id TEXT
#2074	);
#2075
#2076	CREATE TABLE llm_calls
#2077	(
#2078	call_id TEXT PRIMARY KEY,
#2079	pid TEXT,
#2080	image_id TEXT,
#2081	purpose TEXT NOT NULL,
#2082	status TEXT NOT NULL,
#2083	api TEXT,
#2084	model TEXT,
#2085	request_id TEXT,
#2086	response_id TEXT,
#2087	messages JSONB NOT NULL,
#2088	tools JSONB NOT NULL,
#2089	request_options JSONB NOT NULL,
#2090	response_content TEXT NOT NULL,
#2091	tool_calls JSONB NOT NULL,
#2092	reasoning JSONB,
#2093	usage JSONB NOT NULL,
#2094	raw_response JSONB,
#2095	error TEXT,
#2096	created_at TIMESTAMP NOT NULL,
#2097	completed_at TIMESTAMP
#2098	);
#2099	```
#2100
#2101	真实 LLM 调用是稀缺且可计费资源。除 audit 摘要外，runtime 必须把每次请求的完整输入、可见 tool schema、模型输出、tool call、usage/token 统计、provider 暴露的 reasoning 字段、raw response 和错误信息持久化到 `llm_calls` 一类表中，供复盘、成本核算和调试使用。
#2102
#2103	---
#2104
#2105	## 10. 开发阶段规划
#2106
#2107	## Phase 0：概念验证
#2108
#2109	目标：跑通单 Agent + Object Memory + Tool Call。
#2110
#2111	交付：
#2112
#2113	- Python SDK；
#2114	- ObjectStore；
#2115	- ProcessManager 单进程版本；
#2116	- ToolBroker 调用静态工具；
#2117	- AuditLog；
#2118	- 简单 CLI。
#2119
#2120	验收：
#2121
#2122	- 能创建 task object；
#2123	- 能 materialize context；
#2124	- 能调用 read/test 工具；
#2125	- 所有动作有 audit record。
#2126
#2127	## Phase 1：Human Interrupt + Capability
#2128
#2129	目标：加入人类授权和中断。
#2130
#2131	交付：
#2132
#2133	- CapabilityManager；
#2134	- HumanRequest；
#2135	- interrupt/resume；
#2136	- approval flow；
#2137	- debug console。
#2138
#2139	验收：
#2140
#2141	- 高风险工具调用会被拦截；
#2142	- 人类 approve 后恢复执行；
#2143	- 人类 pause/cancel 可以中断进程；
#2144	- capability grant/revoke 可追踪。
#2145
#2146	## Phase 2：fork worker + MemoryView
#2147
#2148	目标：实现子 Agent 和受限内存视图。
#2149
#2150	交付：
#2151
#2152	- fork restricted/worker；
#2153	- wait/join；
#2154	- MemoryView fork；
#2155	- child result merge；
#2156	- resource budget。
#2157
#2158	验收：
#2159
#2160	- Root Agent 可 fork worker 分析日志；
#2161	- worker 无法访问未授权对象；
#2162	- worker 输出可合并回 root memory；
#2163	- fork 行为有 audit trace。
#2164
#2165	## Phase 3：Skill Linker
#2166
#2167	目标：实现动态 skill 加载。
#2168
#2169	交付：
#2170
#2171	- Skill schema；
#2172	- Skill registry；
#2173	- lazy loading；
#2174	- compatibility check；
#2175	- skill audit。
#2176
#2177	验收：
#2178
#2179	- Agent 可 discover/load/unload skill；
#2180	- skill 不自动获得外部副作用权限；
#2181	- materializer 能按需展开 skill 内容。
#2182
#2183	## Phase 4：JIT Tool
#2184
#2185	目标：实现受控工具生成。
#2186
#2187	交付：
#2188
#2189	- ToolCandidateObject；
#2190	- sandbox build/test；
#2191	- static checks；
#2192	- ephemeral registration；
#2193	- ToolHandle；
#2194	- human approval integration。
#2195
#2196	验收：
#2197
#2198	- Agent 可提出日志解析工具；
#2199	- 工具在 sandbox 中测试；
#2200	- 通过后以 ephemeral tool 注册；
#2201	- Agent 可调用新工具；
#2202	- 注册过程完整审计。
#2203
#2204	## Phase 5：exec + checkpoint/rollback
#2205
#2206	目标：实现进程镜像切换和恢复。
#2207
#2208	交付：
#2209
#2210	- AgentImage registry；
#2211	- exec check；
#2212	- checkpoint create/restore；
#2213	- rollback object view；
#2214	- diff report。
#2215
#2216	验收：
#2217
#2218	- Agent 可从 base-agent exec 到 coding-agent；
#2219	- exec 不提升权限；
#2220	- checkpoint 可恢复状态；
#2221	- rollback 可撤销 object memory 修改。
#2222
#2223	---
#2224
#2225	## 11. 测试计划
#2226
#2227	## 11.1 单元测试
#2228
#2229	覆盖：
#2230
#2231	- ObjectStore CRUD；
#2232	- ObjectHandle 权限检查；
#2233	- ObjectLink 查询；
#2234	- MemoryView fork/merge；
#2235	- Capability grant/revoke/check；
#2236	- Event send/recv/interrupt；
#2237	- Process fork/exec/wait；
#2238	- Skill load verification；
#2239	- Tool candidate validation；
#2240	- Audit record 写入。
#2241
#2242	## 11.2 集成测试
#2243
#2244	场景：
#2245
#2246	1. 单 Agent 完成简单任务；
#2247	2. 高风险工具调用触发 human approval；
#2248	3. human interrupt pause/resume；
#2249	4. fork worker 分析输入；
#2250	5. JIT tool 生成并调用；
#2251	6. checkpoint 后 rollback；
#2252	7. exec 后继续执行。
#2253
#2254	## 11.3 安全测试
#2255
#2256	必须测试：
#2257
#2258	- 子进程越权访问对象；
#2259	- 子进程继承过多 capability；
#2260	- JIT tool 请求网络但未授权；
#2261	- JIT tool 访问凭据；
#2262	- skill 中包含 prompt injection；
#2263	- tool output injection；
#2264	- fork bomb；
#2265	- audit log tampering；
#2266	- revoked capability 继续使用；
#2267	- human approval spoofing。
#2268
#2269	## 11.4 性能测试
#2270
#2271	指标：
#2272
#2273	- object query latency；
#2274	- materialization latency；
#2275	- event dispatch latency；
#2276	- tool sandbox startup time；
#2277	- fork worker overhead；
#2278	- audit write throughput；
#2279	- token budget utilization；
#2280	- memory view merge cost。
#2281
#2282	---
#2283
#2284	## 12. 评估指标
#2285
#2286	## 12.1 任务指标
#2287
#2288	- task success rate；
#2289	- wall-clock time；
#2290	- number of tool calls；
#2291	- number of human interruptions；
#2292	- number of failed actions；
#2293	- rollback count；
#2294	- JIT tool reuse rate；
#2295	- child process usefulness。
#2296
#2297	## 12.2 安全指标
#2298
#2299	- unauthorized access attempts blocked；
#2300	- unnecessary capability grants；
#2301	- missed approval requirements；
#2302	- dangerous action prevention rate；
#2303	- audit completeness；
#2304	- rollback effectiveness。
#2305
#2306	## 12.3 人类交互指标
#2307
#2308	- unnecessary human query rate；
#2309	- average human response burden；
#2310	- approval latency；
#2311	- interruption recovery latency；
#2312	- human override success rate；
#2313	- status explainability score。
#2314
#2315	## 12.4 内存指标
#2316
#2317	- context materialization precision；
#2318	- object retrieval relevance；
#2319	- stale object usage rate；
#2320	- duplicate object rate；
#2321	- provenance completeness；
#2322	- merge conflict rate。
#2323
#2324	---
#2325
#2326	## 13. Python SDK 草案
#2327
#2328	```python
#2329	from agent_libos import Runtime, AgentImage, Rights
#2330
#2331	runtime = Runtime.open("local")
#2332
#2333	root = runtime.process.spawn(
#2334	image="coding-agent:v0",
#2335	goal={"text": "Fix failing tests in this repository"},
#2336	capabilities=[
#2337	runtime.capability.project_read("repo"),
#2338	runtime.capability.tool_call("pytest", rights={Rights.EXECUTE}),
#2339	],
#2340	)
#2341
#2342	log_obj = runtime.memory.create_object(
#2343	pid=root,
#2344	type="error_trace",
#2345	payload={"log": "..."},
#2346	)
#2347
#2348	worker = runtime.process.fork(
#2349	parent=root,
#2350	goal={"text": "Analyze the test failure log"},
#2351	memory_view=runtime.memory.view([log_obj], mode="read_only"),
#2352	capabilities=[],
#2353	mode="worker",
#2354	)
#2355
#2356	result = runtime.process.wait(root, worker)
#2357
#2358	candidate = runtime.tools.propose(
#2359	pid=root,
#2360	spec={
#2361	"name": "parse_pytest_log",
#2362	"description": "Parse pytest failure logs into structured failures",
#2363	"input_schema": {"type": "object", "properties": {"log": {"type": "string"}}},
#2364	"output_schema": {"type": "array"},
#2365	},
#2366	source_code="...",
#2367	tests=[...],
#2368	requested_capabilities=[],
#2369	)
#2370
#2371	validation = runtime.tools.validate(candidate)
#2372	if validation.ok:
#2373	tool = runtime.tools.register(
#2374	approver="policy:local",
#2375	candidate=candidate,
#2376	scope="ephemeral_process",
#2377	)
#2378
#2379	call = runtime.tools.call(root, tool, {"log": "..."})
#2380	parsed = runtime.tools.get_result(root, call)
#2381
#2382	runtime.human.query(
#2383	pid=root,
#2384	human="owner",
#2385	request={
#2386	"type": "approval",
#2387	"question": "Apply this patch to the repository?",
#2388	"context_objects": [parsed],
#2389	"blocking": True,
#2390	"risk_level": "medium",
#2391	},
#2392	)
#2393	```
#2394
#2395	---
#2396
#2397	## 14. 需要尽早确定的设计决策
#2398
#2399	### 14.1 Agent Process 是强 actor 还是 workflow wrapper？
#2400
#2401	两种路线：
#2402
#2403	1. Actor-first：AgentProcess 是消息驱动 actor；
#2404	2. Workflow-first：AgentProcess 是持久 workflow 的包装。
#2405
#2406	建议 MVP 采用 workflow-first，内部保留 actor-like API。这样更容易实现 checkpoint、wait、human approval。
#2407
#2408	### 14.2 Object payload 存 JSON 还是 blob？
#2409
#2410	建议：
#2411
#2412	- 小对象：JSONB；
#2413	- 大对象：blob store；
#2414	- 所有对象都保留 metadata、summary、token_estimate。
#2415
#2416	### 14.3 Context materialization 是否可插拔？
#2417
#2418	必须可插拔。不同 AgentImage 应有不同 ContextPolicy。
#2419
#2420	### 14.4 JIT tool 支持哪些语言？
#2421
#2422	MVP 只支持 Python。后续支持 Rust/JS/WASM。
#2423
#2424	### 14.5 Sandbox 选型
#2425
#2426	MVP 可用 Docker，但接口要抽象为：
#2427
#2428	```python
#2429	class SandboxBackend:
#2430	def build(...): ...
#2431
#2432	def run(...): ...
#2433
#2434	def inspect(...): ...
#2435
#2436	def destroy(...): ...
#2437	```
#2438
#2439	后续可替换为 Firecracker、gVisor、WASM sandbox。
#2440
#2441	---
#2442
#2443	## 15. 非目标
#2444
#2445	第一阶段不追求：
#2446
#2447	- 完全自主的无限期 Agent；
#2448	- 无限制自我修改；
#2449	- 全自动全局工具市场；
#2450	- 完整 POSIX 兼容；
#2451	- 字节级内存模型；
#2452	- 文件系统作为根命名空间；
#2453	- 无人监管的高风险外部副作用；
#2454	- 多用户企业权限体系；
#2455	- 大规模分布式 agent cluster。
#2456
#2457	---
#2458
#2459	## 16. 总结
#2460
#2461	本框架的核心不是再做一个 workflow engine，也不是再做一个 tool-calling agent 框架，而是实现一个 Agent-native libOS 以及其上的
#2462	LLM-facing Skills / Tools Layer：
#2463
#2464	```text
#2465	Agent Process
#2466	+ Skills / Tools Layer
#2467	+ Object Memory
#2468	+ Event System
#2469	+ Capability Security
#2470	+ HumanObject Interrupts
#2471	+ Skill Dynamic Linking
#2472	+ JIT Tool Broker
#2473	+ Checkpoint/Rollback
#2474	+ Audit Trace
#2475	```
#2476
#2477	其中，libOS 提供稳定、可审计、受 capability 管控的底层原语；Skills / Tools Layer 则把这些原语包装成 LLM 能够可靠使用的
#2478	actions、skills、tool bundles 和 workflow macros。
#2479
#2480	最有辨识度的原语是：
#2481
#2482	```text
#2483	fork
#2484	exec
#2485	signal
#2486	checkpoint
#2487	rollback
#2488	fork_view
#2489	merge_view
#2490	materialize_context
#2491	dlopen_skill
#2492	propose_tool
#2493	register_tool
#2494	human_interrupt
#2495	capability_grant
#2496	capability_revoke
#2497	```
#2498
#2499	最重要的工程原则是：
#2500
#2501	> Agent 可以自主扩展执行能力，但所有能力扩展必须经过 capability-safe runtime control。
#2502
#2503	最重要的内存原则是：
#2504
#2505	> Agent memory is not byte-addressed memory and not a filesystem namespace; it is a typed, capability-protected,
#2506	> versioned object graph from which execution contexts are materialized.
#2507
#2508	如果团队按照本文档推进，第一阶段应优先做出一个可运行的 coding-agent demo，用最小系统验证：process、object
#2509	memory、capability、human interrupt、JIT tool 和 audit trace 是否能自然协作。
#2510

z6MkqRzA/yingqi-z20-Agent-libOS