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、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、tsconfig.json

工作区与包管理

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

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

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

资料来源：package.json、README.md

AI 协作约定

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

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

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

资料来源：AGENTS.md、CLAUDE.md

模块组织示意图

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

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、package.json、tsconfig.json、tsconfig.base.json、AGENTS.md、CLAUDE.md

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. 数据流与调用关系

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

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

概述与定位

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 落盘的典型数据流：

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`

概述与设计目标

沙箱模块的边界由 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

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

核心架构与模块协作

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

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

Pitfall Log / 踩坑日志

项目：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