> For the complete documentation index, see [llms.txt](https://rokurokulab.gitbook.io/roku-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rokurokulab.gitbook.io/roku-docs/crates/roku-common-types.md).

# roku-common-types

`roku-common-types` 是 workspace 里几乎所有 crate 都依赖的共享类型库。它不含任何业务逻辑，只承载跨 crate 共享的数据结构、枚举和少量纯函数——目的是避免 crate 间的循环依赖。它是依赖树的叶节点，自身只依赖 `serde`、`serde_json`、`time`，不引用任何内部 crate。

## 主要类型

`lib.rs` 直接定义了大量共享类型，同时通过子模块 re-export 补充其余部分。

**ID 类型**是一批 newtype 包装：`TaskId`、`NodeId`、`RequestId`、`ApprovalId`、`ArtifactId`、`ExperimentRunId`。

**会话与请求**：`ConversationRole`（User/Assistant/System）、`ConversationTurn`（role + content + created\_at\_unix\_ms）、`RequestEnvelope`（session\_id、goal、conversation\_history、model\_override 等）、`ResponseEnvelope`（request\_id、status、message、artifacts）、`ResponseStatus`（Succeeded/PendingApproval/Failed）。

**任务状态机**：`TaskState` 有 14 个状态（Queued → Planning → ... → Succeeded/Failed/Cancelled 等），`Task` 是完整任务快照，`TaskEvent` 记录状态转换，`TaskReplayReport` / `TaskReplaySnapshot` / `TaskReplayCursor` 支持 replay，`ReplayConsistencyStatus` / `RecoveryEligibility` / `ResumeCandidate` 支持恢复判断。

**计划与节点**：`PlanOutline`、`PlanStep`、`TaskNode`（含 retry、join、aggregation、recovery\_anchor、budget\_snapshot 等策略字段）、`TaskNodeKind`、`TaskNodeDispatchPolicy`、`JoinPolicy`、`AggregationMode`、`RetryPolicy`、`RerunPolicy`。

**Agent 上下文**：`AgentContext`、`AgentInstanceSpec`、`PolicyBindings`、`CapabilityToken`，以及 `RuntimeMemorySections`（short\_term\_continuity / long\_term\_recall / working\_memory 三段文本）。

**工具契约**：`ToolContract`（selection / input / output / runtime / grounding 五个子契约）、`ToolRuntimeContract`（含 `is_concurrency_safe()` 方法）、`ToolGroundingContract`、`GroundingStrategy`、`ExtractionHint`、`ToolOutputEnvelope`（ok、terminal、message、data）、`GeneralExecuteCompletion`。

**运行时追踪**：`RuntimeLoopTrace`、`RuntimeLoopTraceStep`、`RuntimeLoopTraceDecision`、`RuntimeLoopTraceOutcome`，以及 `RuntimeLoopExecutionTrace` 系列。

**结果与工件**：`ResultEnvelope`（task\_id、node\_id、producer、status、payload、confidence）、`Artifact`（artifact\_id、uri、checksum、metadata）、`EvidenceItem`、`ValidationEvidenceSet`、`NodeResultSet`、`ValidationReport`。

**错误与补偿**：`RuntimeError`（实现了 `std::error::Error`）、`ErrorClass`（Validation/Dependency/Timeout/Security/BudgetExhausted/NonRetriable）、`CompensationRecord`、`CompensationAction`。

## 审批流程类型

`approval.rs` 定义了审批流程的核心类型：`ApprovalStatus`（Pending/Approved/Rejected/Cancelled）、`ApprovalDecision`（actor、approved、comment）、`PendingExecutionApproval`（approval\_id、digest、canonical\_execution、policy\_decision）、`ApprovalTicket`，以及 `ApprovedExecutionRef`（审批通过后的引用摘要）。

`canonical_execution.rs` 定义工具执行的规范化表示：`CanonicalExecution`（tool\_name、program、argv、cwd、invocation\_mode、shell\_context、action\_class、env\_policy、resource\_scope、digest）、`CanonicalDigest`、`InvocationMode`（DirectExec / ShellWrapped）、`ExecutionActionClass`（Read/Write/Exec/Network/Mixed）。审批者看到的是 canonical 表示，而不是原始参数字符串。

`execution_policy.rs` 定义策略决策的输出：`PolicyOutcome`（Allow/Deny/RequireApproval）、`PolicyDecision`（outcome + reason\_code + optional approval\_requirement）、`PolicyReasonCode`。

`execution_preview.rs` 定义展示给用户的只读投影：`ExecutionPreview`（tool\_name、digest、summary、command\_text、working\_directory）。注释里明确说明 preview 从 canonical execution 派生，但绝不能作为审批、执行或恢复的真相来源。目前 `project_execution_preview` 只处理 Bash 工具的 DirectExec 模式，其他返回 None。

这几个类型的概念层次是：`CanonicalExecution`（真相）→ `PolicyDecision`（策略判断）→ `PendingExecutionApproval` / `ApprovalTicket`（存入 control plane 等待决策）→ `ExecutionPreview`（仅供 UI 显示）。

## Catalog

`catalog/` 下定义工具/技能的发现能力。`CatalogDescriptor` 是工具/技能的元数据，包含 selector、kind、role、description、selection\_hint、tags、examples、risk、cost、contract 等字段。`ResourceCatalog` 内置 BM25（k1=1.5，b=0.75）和 64 维 embedding 的检索逻辑，让 tool router 可以基于自然语言目标匹配工具，而不是硬编码列表。`build_resource_catalog` 从描述符列表构建目录。检索参数（`EMBEDDING_DIMENSIONS`、`BM25_K1`、`BM25_B`）是代码内硬编码常量，不可运行时配置。

## 可观测性

`observability/` 分两层：`mod.rs` 提供 `TraceContext`、`AuditCorrelation`、`Metrics`（AtomicU64 计数器，跟踪 requests、failures、approvals、experiments）；`logging.rs` 提供 `LogLevel`、`LogSink` trait、`StderrLogSink`、`FanoutLogSink`、`AsyncRotatingFileLogSink`、`emit_global_log`、`install_global_log_sink`。`observability::*` 在 `lib.rs` 中以 glob re-export 方式暴露。

> \[未查明] `Metrics` 的聚合/暴露机制（是否有 Prometheus 导出路径）。

## 使用方

workspace 内几乎所有 crate 都依赖它：`roku-memory`、`roku-agent-runtime`、`roku-api-gateway`、`roku-cmd`、`roku-plugin-host`、`roku-plugin-llm`、`roku-plugin-mcp`、`roku-plugin-skills`、`roku-plugin-telegram`、`roku-plugin-tools`、`roku-plugin-memory-openviking`、`roku-plugin-memory-sqlite`。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://rokurokulab.gitbook.io/roku-docs/crates/roku-common-types.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.