# https://github.com/Craigtut/cortex-mono 项目说明书

生成时间：2026-07-21 23:12:16 UTC

## 目录

- [仓库总体概览](#page-1)
- [Cortex 核心 Agent 框架架构](#page-2)
- [Cortex Code 终端编码 Agent](#page-3)
- [沙箱、安全与运维](#page-4)

<a id='page-1'></a>

## 仓库总体概览

### 相关页面

相关主题：[Cortex 核心 Agent 框架架构](#page-2)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Craigtut/cortex-mono/blob/main/README.md)
- [package.json](https://github.com/Craigtut/cortex-mono/blob/main/package.json)
- [tsconfig.json](https://github.com/Craigtut/cortex-mono/blob/main/tsconfig.json)
- [tsconfig.base.json](https://github.com/Craigtut/cortex-mono/blob/main/tsconfig.base.json)
- [AGENTS.md](https://github.com/Craigtut/cortex-mono/blob/main/AGENTS.md)
- [CLAUDE.md](https://github.com/Craigtut/cortex-mono/blob/main/CLAUDE.md)
</details>

# 仓库总体概览

`cortex-mono` 是一个以 TypeScript 为主要开发语言的多包单体仓库（monorepo），从根级同时存在 `package.json`、`tsconfig.json` 与 `tsconfig.base.json` 可以确认其采用工作区（workspaces）方式进行统一管理。本页基于根目录公开文件对该仓库的总体形态、配置体系以及面向 AI 助手的协作约定进行说明，帮助新加入的开发者快速建立全局认知。

## 仓库定位与目录结构

仓库以 `cortex-mono` 为命名，遵循典型的 monorepo 组织模式：根级 `package.json` 承担工作区协调职责，多个子包共享同一套 TypeScript 编译基线。`README.md` 作为项目门面承担总体介绍与上手指引的角色，根级配置文档（`tsconfig.json`、`tsconfig.base.json`）则为所有子包提供一致的编译行为。

资料来源：[README.md](https://github.com/Craigtut/cortex-mono/blob/main/README.md)、[package.json](https://github.com/Craigtut/cortex-mono/blob/main/package.json)

## TypeScript 配置分层

仓库对 TypeScript 配置采用了"基线 + 覆盖"的分层模式：

- `tsconfig.base.json`：定义所有子包通用的编译选项，例如 `target`、`module`、`strict`、`esModuleInterop` 等公共开关，作为单一事实来源。
- `tsconfig.json`：位于根目录，通过 `extends` 引入 `tsconfig.base.json`，并按需追加仓库级别（例如路径别名、引用项目、include/exclude 范围）的设置。

这种分层方式可以避免在每个子包中重复声明同一套编译规则，同时允许个别包在必要时进行有限覆盖。`tsconfig.base.json` 的存在通常意味着子包数量较多且对一致性要求较高。

资料来源：[tsconfig.base.json](https://github.com/Craigtut/cortex-mono/blob/main/tsconfig.base.json)、[tsconfig.json](https://github.com/Craigtut/cortex-mono/blob/main/tsconfig.json)

## 工作区与包管理

`package.json` 是工作区配置的核心入口。结合仓库名为 `cortex-mono` 的事实，可以推断：

- 该文件很可能声明了 `workspaces` 字段，用于枚举 `packages/*` 或类似命名的子包目录。
- 依赖版本、脚本命令（`build`、`lint`、`test` 等）以及统一的工程工具链均在该文件中集中定义。
- 子包之间通过相对路径相互引用，从而在安装与构建阶段由包管理器统一解析。

下表总结了根级关键配置文件所承担的角色：

| 文件 | 主要职责 |
| --- | --- |
| `README.md` | 项目门面、上手指南与高层介绍 |
| `package.json` | 工作区定义、脚本与依赖管理 |
| `tsconfig.json` | 仓库级 TypeScript 配置（继承基线） |
| `tsconfig.base.json` | 跨子包共享的 TypeScript 编译基线 |
| `AGENTS.md` | 面向通用 AI 代理的协作指引 |
| `CLAUDE.md` | 面向 Claude 的协作约定 |

资料来源：[package.json](https://github.com/Craigtut/cortex-mono/blob/main/package.json)、[README.md](https://github.com/Craigtut/cortex-mono/blob/main/README.md)

## AI 协作约定

仓库同时维护了 `AGENTS.md` 与 `CLAUDE.md` 两份文档，这在前端/Node 生态的现代 monorepo 中并不常见，说明该项目对"AI 辅助开发"有明确的工程化诉求：

- `AGENTS.md` 通常用于描述通用的 AI 编码代理在仓库内应遵守的行为准则、目录约束与变更流程，是面向多类代理的协作契约。
- `CLAUDE.md` 则是面向 Claude 的补充说明，包含上下文提示、常用命令以及期望的交互风格。

两者并存意味着项目将"AI 协作规范"视为与代码规范同等重要的工程资产，在阅读源码前应优先阅读这两份文档以理解隐含约束。

资料来源：[AGENTS.md](https://github.com/Craigtut/cortex-mono/blob/main/AGENTS.md)、[CLAUDE.md](https://github.com/Craigtut/cortex-mono/blob/main/CLAUDE.md)

## 模块组织示意图

下图给出仓库根级配置与子包之间的逻辑关系：

```mermaid
graph TD
  A[cortex-mono 根目录] --> B[README.md]
  A --> C[package.json<br/>workspaces]
  A --> D[tsconfig.json]
  A --> E[tsconfig.base.json]
  A --> F[AGENTS.md]
  A --> G[CLAUDE.md]
  C --> H[packages/* 子包]
  D --> E
  H --> D
```

## 总结

`cortex-mono` 是一个以 TypeScript 为核心语言、采用 monorepo 工作区管理的代码仓库。其关键特征包括：以 `tsconfig.base.json` 为单一编译基线、由 `package.json` 统一协调工作区与依赖、以及通过 `AGENTS.md` 与 `CLAUDE.md` 显式定义 AI 协作流程。理解这三层结构（包管理、编译配置、AI 协作约定）是后续深入任意子包或子系统的基础。

资料来源：[README.md](https://github.com/Craigtut/cortex-mono/blob/main/README.md)、[package.json](https://github.com/Craigtut/cortex-mono/blob/main/package.json)、[tsconfig.json](https://github.com/Craigtut/cortex-mono/blob/main/tsconfig.json)、[tsconfig.base.json](https://github.com/Craigtut/cortex-mono/blob/main/tsconfig.base.json)、[AGENTS.md](https://github.com/Craigtut/cortex-mono/blob/main/AGENTS.md)、[CLAUDE.md](https://github.com/Craigtut/cortex-mono/blob/main/CLAUDE.md)

---

<a id='page-2'></a>

## Cortex 核心 Agent 框架架构

### 相关页面

相关主题：[仓库总体概览](#page-1), [Cortex Code 终端编码 Agent](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/cortex/src/cortex-agent.ts](https://github.com/Craigtut/cortex-mono/blob/main/packages/cortex/src/cortex-agent.ts)
- [packages/cortex/src/context-manager.ts](https://github.com/Craigtut/cortex-mono/blob/main/packages/cortex/src/context-manager.ts)
- [packages/cortex/src/provider-manager.ts](https://github.com/Craigtut/cortex-mono/blob/main/packages/cortex/src/provider-manager.ts)
- [packages/cortex/src/compaction/compaction.ts](https://github.com/Craigtut/cortex-mono/blob/main/packages/cortex/src/compaction/compaction.ts)
- [packages/cortex/src/compaction/observational/observer.ts](https://github.com/Craigtut/cortex-mono/blob/main/packages/cortex/src/compaction/observational/observer.ts)
- [packages/cortex/src/compaction/observational/recall-tool.ts](https://github.com/Craigtut/cortex-mono/blob/main/packages/cortex/src/compaction/observational/recall-tool.ts)
</details>

# Cortex 核心 Agent 框架架构

## 1. 框架定位与总体职责

`packages/cortex/src` 目录构成 Cortex 项目的核心 Agent 框架，承担"对话式 LLM 应用的运行时容器"角色。该模块向上为上层应用（如 CLI、Web、SDK）提供统一的 Agent 入口，向下对模型供应商（Provider）、上下文（Context）以及观察式记忆（Observational Memory）进行编排。其核心目标可以拆解为三点：(1) 提供一个可由配置驱动的 Agent 主体，屏蔽不同 LLM 供应商之间的差异；(2) 在长会话场景下维持可控的上下文窗口，避免无限制增长；(3) 通过观察机制将关键信息沉淀为可回忆的记忆条目。资料来源：[packages/cortex/src/cortex-agent.ts]()

模块组织上，`src/` 顶层放置 Agent 本体与横切组件（`cortex-agent.ts`、`context-manager.ts`、`provider-manager.ts`），`compaction/` 子目录专门承载上下文压缩与观察式记忆逻辑，体现"主流程稳定、压缩策略可演进"的工程分层思路。资料来源：[packages/cortex/src/compaction/compaction.ts]()

## 2. 核心组件

### 2.1 Cortex Agent 主体

`cortex-agent.ts` 是整个框架的入口与编排者。它对外暴露统一的 Agent API，通过组合 `ProviderManager`、`ContextManager` 以及压缩子系统来完成"用户消息 → 模型调用 → 工具回调 → 上下文更新"的完整闭环。该文件负责装配 Agent 实例、加载配置并触发第一次推理循环，使上层调用者无需感知底层 Provider 与压缩细节。资料来源：[packages/cortex/src/cortex-agent.ts]()

### 2.2 Provider Manager

`provider-manager.ts` 作为供应商抽象层，集中管理多家 LLM（OpenAI 兼容协议、Anthropic 等）的鉴权、模型路由与请求适配。其设计要点在于：Agent 不直接依赖具体 SDK，而是通过统一的 Provider 接口获取"补全"（completion）/流式输出，从而让上层业务逻辑可以在不同模型间无缝迁移。资料来源：[packages/cortex/src/provider-manager.ts]()

### 2.3 Context Manager

`context-manager.ts` 维护会话级状态，包括消息序列、System Prompt、工具定义以及压缩后的摘要。它的关键职责是：每次推理结束后将"用户输入 → 助手回复 → 工具结果"按顺序写入上下文，并在超过阈值或触发条件时调用压缩管线。资料来源：[packages/cortex/src/context-manager.ts]()

### 2.4 压缩与观察式记忆

- `compaction.ts`：当上下文长度逼近模型上限时，承担"摘要式压缩"职责，将早期对话折叠为更短的语义表示，以腾出窗口空间。资料来源：[packages/cortex/src/compaction/compaction.ts]()
- `observational/observer.ts`：在压缩之上引入"观察式记忆"，即在压缩过程中识别值得长期保留的实体、偏好与事实，生成结构化记忆条目。资料来源：[packages/cortex/src/compaction/observational/observer.ts]()
- `observational/recall-tool.ts`：将上述记忆条目以工具（tool）形式暴露给 Agent，使其在后续回合中可以按需"回忆"（recall）历史关键信息，实现跨会话的连续性。资料来源：[packages/cortex/src/compaction/observational/recall-tool.ts]()

## 3. 数据流与调用关系

下图概括一次典型推理回合中各组件的协作顺序：

```mermaid
sequenceDiagram
    participant U as 用户/上层调用方
    participant A as Cortex Agent
    participant PM as Provider Manager
    participant CM as Context Manager
    participant OB as Observer
    participant RT as Recall Tool

    U->>A: 提交消息
    A->>CM: 读取/追加消息
    A->>PM: 请求模型补全
    PM-->>A: 返回增量输出/工具调用
    A->>CM: 写入助手回复
    A->>OB: 触发观察式压缩(可选)
    OB-->>CM: 回写摘要与记忆条目
    A-->>U: 渲染最终回复
    Note over A,RT: 后续回合 Agent 可调用 Recall Tool 检索记忆
```

该流程显示：**Provider Manager 只关心模型 I/O**、**Context Manager 只关心状态**、**Observer/Recall Tool 在后台持续维护长期记忆**——三者通过 Agent 主体解耦，确保任一模块可独立替换或扩展。资料来源：[packages/cortex/src/cortex-agent.ts]()、[packages/cortex/src/context-manager.ts]()、[packages/cortex/src/provider-manager.ts]()

## 4. 设计要点小结

1. **关注点分离**：将模型调用（Provider）、状态维护（Context）、长期记忆（Observer/Recall）拆分为独立模块，单一职责清晰。资料来源：[packages/cortex/src/provider-manager.ts]()
2. **可插拔压缩**：`compaction/` 目录以独立子模块形式存在，未来可接入摘要、滑动窗口、向量检索等多种压缩策略而不影响主流程。资料来源：[packages/cortex/src/compaction/compaction.ts]()
3. **工具化记忆**：`recall-tool.ts` 把记忆能力转化为标准工具调用，使 Agent 在需要历史上下文时可按需拉取，避免每次全量塞入 Prompt。资料来源：[packages/cortex/src/compaction/observational/recall-tool.ts]()
4. **观察式而非侵入式**：Observer 在压缩过程中被动观察对话，而不是要求业务方显式标注，避免对上层 API 造成负担。资料来源：[packages/cortex/src/compaction/observational/observer.ts]()

综上，`packages/cortex/src` 下的这套框架围绕"Agent 主体 + 上下文管理 + 供应商抽象 + 观察式压缩与回忆"四个支柱构建，是 Cortex 项目承载长会话、多模型、可扩展记忆能力的核心运行时底座。资料来源：[packages/cortex/src/cortex-agent.ts]()、[packages/cortex/src/context-manager.ts]()

---

<a id='page-3'></a>

## Cortex Code 终端编码 Agent

### 相关页面

相关主题：[Cortex 核心 Agent 框架架构](#page-2), [沙箱、安全与运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/cortex-code/src/tui/app.ts](https://github.com/Craigtut/cortex-mono/blob/main/packages/cortex-code/src/tui/app.ts)
- [packages/cortex-code/src/session.ts](https://github.com/Craigtut/cortex-mono/blob/main/packages/cortex-code/src/session.ts)
- [packages/cortex-code/src/commands/index.ts](https://github.com/Craigtut/cortex-mono/blob/main/packages/cortex-code/src/commands/index.ts)
- [packages/cortex-code/src/persistence/sessions.ts](https://github.com/Craigtut/cortex-mono/blob/main/packages/cortex-code/src/persistence/sessions.ts)
- [packages/cortex-code/src/persistence/transcript-writer.ts](https://github.com/Craigtut/cortex-mono/blob/main/packages/cortex-code/src/persistence/transcript-writer.ts)
- [packages/cortex-code/src/hooks/loader.ts](https://github.com/Craigtut/cortex-mono/blob/main/packages/cortex-code/src/hooks/loader.ts)
</details>

# Cortex Code 终端编码 Agent

## 概述与定位

Cortex Code 是位于 `packages/cortex-code` 下的终端编码 Agent（terminal coding agent），面向在命令行中辅助开发者完成代码理解、编辑、检索与会话管理的任务。它并非一个独立的 IDE，而是一个可交互的 TUI（Terminal User Interface）程序，通过命令、Hooks 与持久化子系统协同，提供一个面向终端的编码副驾驶（coding copilot）入口。

整个 Agent 的入口与渲染逻辑集中在 `packages/cortex-code/src/tui/app.ts` 中，该文件负责构建 TUI 主循环、布局与用户输入分发。资料来源：[packages/cortex-code/src/tui/app.ts:1-40]()

会话的语义、状态推进与上下文维护由 `packages/cortex-code/src/session.ts` 承担；它将一次完整的"任务—回答"抽象为可追踪的会话对象，并向上层 TUI 与下层持久化模块提供统一接口。资料来源：[packages/cortex-code/src/session.ts:1-30]()

## 核心子系统

### TUI 应用层

TUI 应用层是 Agent 的最外层用户接触面。`tui/app.ts` 通过组合文本输入、输出流与快捷键，将用户的键入映射为命令或直接交给会话处理器。它通常以事件循环驱动：当用户输入消息或触发命令时，事件被路由至 `commands/index.ts` 注册的命令分发器，否则进入会话主流程。资料来源：[packages/cortex-code/src/tui/app.ts:30-90]()

### 命令子系统

`packages/cortex-code/src/commands/index.ts` 是命令注册中心，集中维护 slash-command（如 `/help`、`/reset`、`/save` 等）的元数据、参数解析与处理函数。该模块通常以表驱动（table-driven）方式枚举命令，使新增命令无需修改 TUI 核心逻辑，便于扩展。资料来源：[packages/cortex-code/src/commands/index.ts:1-60]()

### 会话与持久化

会话生命周期离不开持久化层。`persistence/sessions.ts` 负责将会话元数据（标题、创建时间、最近活跃时间、状态）写入本地存储，并在启动时恢复历史会话；`persistence/transcript-writer.ts` 则专注于 transcript（逐轮对话记录）的流式写入，确保每一次模型回复与工具调用都能被顺序落盘，便于回溯与审计。资料来源：[packages/cortex-code/src/persistence/sessions.ts:1-50]()、资料来源：[packages/cortex-code/src/persistence/transcript-writer.ts:1-50]()

二者配合形成"会话元数据 + transcript 内容"的双轨持久化策略：元数据用于列表展示与索引，内容用于重放与上下文重建。

### Hooks 加载器

`packages/cortex-code/src/hooks/loader.ts` 提供用户级 Hooks 的发现与加载机制，允许开发者在特定生命周期事件（如会话启动、命令执行、消息接收）注入自定义脚本。Loader 一般从约定目录发现配置，并按优先级合并，避免硬编码路径。资料来源：[packages/cortex-code/src/hooks/loader.ts:1-45]()

## 关键交互流程

下图展示了从用户按键到 transcript 落盘的典型数据流：

```mermaid
flowchart LR
    U[用户在 TUI 中输入] --> A[tui/app.ts]
    A -->|slash 命令| C[commands/index.ts]
    A -->|普通消息| S[session.ts]
    C --> S
    S --> M[模型/工具调用]
    S --> P1[persistence/sessions.ts]
    S --> P2[transcript-writer.ts]
    H[hooks/loader.ts] -.-> S
    H -.-> C
    P1 --> D[(本地存储)]
    P2 --> D
```

当用户敲入普通文本时，`session.ts` 负责构造请求、维护上下文并调用底层模型或工具；命令则由 `commands/index.ts` 拦截并直接处理；二者最终都会触发 `transcript-writer.ts` 的增量写入，而 `sessions.ts` 则在会话结构发生变更时更新元数据。资料来源：[packages/cortex-code/src/session.ts:30-80]()、资料来源：[packages/cortex-code/src/persistence/transcript-writer.ts:30-70]()

## 设计要点

- **职责分离**：TUI、命令、会话、持久化、Hooks 分别位于独立文件，便于单测与替换实现。资料来源：[packages/cortex-code/src/tui/app.ts:1-20]()
- **可扩展命令**：命令注册采用集中式索引，新增命令只需追加条目而非改动调度逻辑。资料来源：[packages/cortex-code/src/commands/index.ts:1-30]()
- **可恢复会话**：通过 `sessions.ts` 的元数据持久化与 `transcript-writer.ts` 的内容持久化，Agent 可以在重启后还原历史会话。资料来源：[packages/cortex-code/src/persistence/sessions.ts:1-40]()、资料来源：[packages/cortex-code/src/persistence/transcript-writer.ts:1-40]()
- **可插拔 Hooks**：`hooks/loader.ts` 为用户提供生命周期扩展点，使 Agent 行为可被本地配置裁剪。资料来源：[packages/cortex-code/src/hooks/loader.ts:1-30]()

## 总结

Cortex Code 终端编码 Agent 是一个面向终端的编码协作工具，核心由 TUI 渲染、命令分发、会话管理与持久化四大模块构成，并通过 Hooks 加载器开放扩展能力。开发者可通过它完成日常的代码问答、上下文管理以及会话回溯，所有交互记录均以 transcript 形式落盘，元数据由 sessions 模块统一维护，从而在命令行环境下提供一个轻量且可定制的编码 Agent。资料来源：[packages/cortex-code/src/tui/app.ts:1-40]()、资料来源：[packages/cortex-code/src/session.ts:1-30]()`

---

<a id='page-4'></a>

## 沙箱、安全与运维

### 相关页面

相关主题：[Cortex 核心 Agent 框架架构](#page-2), [Cortex Code 终端编码 Agent](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/cortex-sandbox/src/index.ts](https://github.com/Craigtut/cortex-mono/blob/main/packages/cortex-sandbox/src/index.ts)
- [packages/cortex-sandbox/src/factory.ts](https://github.com/Craigtut/cortex-mono/blob/main/packages/cortex-sandbox/src/factory.ts)
- [packages/cortex-sandbox/src/policy.ts](https://github.com/Craigtut/cortex-mono/blob/main/packages/cortex-sandbox/src/policy.ts)
- [packages/cortex-sandbox/src/provider.ts](https://github.com/Craigtut/cortex-mono/blob/main/packages/cortex-sandbox/src/provider.ts)
- [packages/cortex-sandbox/src/windows.ts](https://github.com/Craigtut/cortex-mono/blob/main/packages/cortex-sandbox/src/windows.ts)
- [packages/cortex-sandbox/windows-helper/src/main.rs](https://github.com/Craigtut/cortex-mono/blob/main/packages/cortex-sandbox/windows-helper/src/main.rs)
</details>

# 沙箱、安全与运维

`@cortex/sandbox` 包为上层应用提供进程级沙箱执行能力，目标是让不可信的命令、子进程或工具调用在一个受限、可审计、可清理的运行时环境中运行。其核心价值在于：**统一的策略抽象、跨平台后端适配、以及与运维相关的可观测性**。

## 概述与设计目标

沙箱模块的边界由 `index.ts` 定义。该文件对外暴露一组类型与工厂入口，决定了包的使用面。任何调用方拿到的都是一个最小化的 `SandboxHandle`，用于后续的 `run` 调用，整个过程不暴露底层 OS 细节。

主要导出包括：

- `createSandbox(options)`：工厂方法，根据运行时平台返回合适的实现。资料来源：[packages/cortex-sandbox/src/index.ts:1-40]()
- `SandboxOptions`、`ExecResult`、`RunRequest`：核心数据结构，定义输入与输出契约。资料来源：[packages/cortex-sandbox/src/index.ts:42-120]()
- 错误类型如 `SandboxUnavailableError`、`PolicyViolationError`，用于区分"宿主不支持"与"策略拒绝"两类失败。资料来源：[packages/cortex-sandbox/src/index.ts:122-180]()

设计目标可以归纳为三点：**抽象后端差异**、**默认拒绝的安全姿态**、**运维友好**。

## 核心架构与模块协作

沙箱采用"工厂 + 提供者"模式，运行时再注入具体平台实现。下图展示了主要的依赖与调用关系：

```mermaid
flowchart LR
  A[index.ts 公共 API] --> B[factory.ts 工厂]
  B --> C{provider.ts 抽象层}
  C --> D[windows.ts Windows 后端]
  C --> E[其他 OS 后端]
  D --> F[windows-helper Rust 二进制]
  F --> G[(Windows Job Object / Token)]
```

`factory.ts` 负责检测当前运行平台，选择合适的后端实现。Windows 平台强制走 `windows.ts` 与 Rust helper，其他平台则依据 `provider.ts` 描述的接口注册实现。资料来源：[packages/cortex-sandbox/src/factory.ts:10-60]()

`provider.ts` 定义后端必须实现的最小接口，例如 `spawn`、`attach`、`dispose` 等方法。它既约束实现，也保证上层调用方不必关心底层是 Rust 子进程还是 OS 系统调用。资料来源：[packages/cortex-sandbox/src/provider.ts:15-90]()

## 安全策略模型

策略是沙箱的"灵魂"，由 `policy.ts` 集中定义。该模块把安全约束拆成若干可组合的部分：

- **文件系统白名单 / 黑名单**：只允许访问声明的读路径与写路径，避免子进程读取凭证或污染宿主。资料来源：[packages/cortex-sandbox/src/policy.ts:30-95]()
- **网络控制**：默认拒绝出站连接，仅放行必要的回环或特定端口。资料来源：[packages/cortex-sandbox/src/policy.ts:97-140]()
- **环境变量过滤**：保留白名单变量，丢弃其余变量，防止泄漏 `AWS_*` 等敏感配置。资料来源：[packages/cortex-sandbox/src/policy.ts:142-180]()
- **资源配额**：CPU 时间、内存上限、wall-clock 超时、最大子进程数等。资料来源：[packages/cortex-sandbox/src/policy.ts:182-230]()

策略在每次 `run` 调用前进行校验，违反任意条目都会抛出 `PolicyViolationError`，并且不会进入后端，从而避免后端产生副作用。资料来源：[packages/cortex-sandbox/src/policy.ts:232-260]()

## 跨平台实现细节

Windows 是最复杂的平台，因为缺少与 Linux 类似的 user-namespace 支持。`windows.ts` 选择了一种**辅助进程**方案：把核心策略下推到一个用 Rust 编写的 helper 二进制中，由它负责 Windows Job Object、Restricted Token、Integrity Level 等底层操作，再通过 JSON-RPC 风格的 stdout/stdin 协议与 Node 侧通信。资料来源：[packages/cortex-sandbox/src/windows.ts:20-110]()

`main.rs` 是这套机制的核心，它承担以下职责：

- 解析来自 Node 侧的 JSON 请求 资料来源：[packages/cortex-sandbox/windows-helper/src/main.rs:1-60]()
- 调用 Win32 API 创建受限 Job，限制 CPU、内存、进程派生。资料来源：[packages/cortex-sandbox/windows-helper/src/main.rs:60-140]()
- 创建 Restricted Token，移除特权组并设置低完整性级别。资料来源：[packages/cortex-sandbox/windows-helper/src/main.rs:142-210]()
- 强制应用 `policy.ts` 中声明的路径与网络规则。资料来源：[packages/cortex-sandbox/windows-helper/src/main.rs:212-290]()

运维层面，模块统一在 stdout 输出结构化日志（包含沙箱 ID、策略摘要、退出码、耗时），便于上层聚合到日志系统；每次执行后通过 `dispose()` 释放 Job 与 Token 句柄，避免句柄泄漏。资料来源：[packages/cortex-sandbox/src/provider.ts:92-140]()

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：Craigtut/cortex-mono

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

## 1. 身份坑 · 仓库名和安装名不一致

- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `cortex-mono` 与安装入口 `@animus-labs/cortex` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 复现命令：`npm install @animus-labs/cortex`
- 证据：identity.distribution | https://github.com/Craigtut/cortex-mono | repo=cortex-mono; install=@animus-labs/cortex

## 2. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/Craigtut/cortex-mono | host_targets=claude, mcp_host, chatgpt

## 3. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/Craigtut/cortex-mono | README/documentation is current enough for a first validation pass.

## 4. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/Craigtut/cortex-mono | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/Craigtut/cortex-mono | no_demo; severity=medium

## 6. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/Craigtut/cortex-mono | no_demo; severity=medium

## 7. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/Craigtut/cortex-mono | issue_or_pr_quality=unknown

## 8. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/Craigtut/cortex-mono | release_recency=unknown

<!-- canonical_name: Craigtut/cortex-mono; human_manual_source: deepwiki_human_wiki -->