Cortx

安全可控的 AI Agent 运行时 — Harness Agent 架构 + Agentic Loop 引擎

Cortex = 大脑皮层。如同大脑皮层负责感知推理、血脑屏障严格过滤、海马体持久记忆 — Cortex Agent 将 Agentic Loop（推理）、PolicyEngine（安全）、Memory（记忆）融为一体。

双语言实现

	Python	TypeScript
位置	`python/cortex_agent/`	`src/`
工具数	69	69
安装	`pip install cortx`	`npm install -g @chnaicorp/cortx`
CLI 命令	`ctx`	`ctx`

💡 PyPI: pip install cortx，npm: npm install -g @chnaicorp/cortx。运行只需 ctx

快速开始

# Python
pip install cortx
ctx

# TypeScript
npm install -g @chnaicorp/cortx
ctx                         # 交互 REPL
ctx -q "hello"              # 单次查询
ctx --model pro             # 指定模型

核心能力

🛠 69 个内置工具

分类	工具
文件	`list_directory` `read_file` `write_file` `edit_file` `glob` `grep` `diff_files` `file_ops` `read_json` `csv_query`
执行	`run_shell_command` `run_python` `execute_sql_query` `python_lint` `run_background_command` `check_server_status` `stop_background_process` `list_background_processes`
网络	`web_search` `web_fetch` `http_request` `set_proxy` `unset_proxy` `show_proxy` `pip_mirror` `npm_mirror`
Git	`git_status` `git_diff` `git_commit` `git_branch` `git_log`
MCP	`mcp_list_servers` `mcp_list_tools` `mcp_call_tool` `mcp_registry` `mcp_install` `mcp_quick` `mcp_session_start` `mcp_session_call` `mcp_session_list_tools` `mcp_session_stop`
浏览器	`browser_navigate`（等待页面加载完成）`browser_snapshot`（获取页面文本）`browser_screenshot`
桌面	`computer_screenshot` `computer_click`
Office	`office_create` `office_send` `office_batch` `office_view` `office_cli` `office_install`
技能	`list_skills` `use_skill` `skill_install` `skill_remove`
子代理	`spawn_subagent`（单个+工具过滤+技能预加载）`spawn_subagents`（并行 fan-out）
记忆/任务	`remember_fact` `recall_fact` `forget_fact` `ask_user` `task_create` `task_list` `task_update`
元工具	`list_tools` `get_current_time` `search_knowledge` `rebuild_knowledge_index`

🎓 技能系统 (Skills)

技能是可复用的专家级指引模板，能为特定任务提供专业方法论：

# 查看所有技能
ctx -q "调用 list_skills 列出你的技能"

# 从 GitHub 安装新技能
ctx -q '用 skill_install 从 GitHub 安装 alchaincyf/huashu-design'

# 加载技能并按其指引工作
ctx -q '用 use_skill 加载 code-review 技能，然后审查 src/core/registry.ts'

7 个内置技能：code-review、refactor、test-writer、doc-writer、debug、explain、architect
自定义技能：放在 .cortx/skills/<name>/SKILL.md，自动发现注册
技能安装：skill_install(source="owner/repo") 从 GitHub 下载，自动注册立即可用
YAML frontmatter 支持 + 递归子目录扫描

🤖 子代理系统 (Subagents)

参考智谱 Coding Agent Subagents 设计，主 agent 可派遣子代理执行独立任务：

# 并行派遣多个子代理
ctx -q '用 spawn_subagents 并行派遣2个子代理：
  子代理1用 code-review 技能审查安全性
  子代理2统计项目 .ts 文件数量'

并行执行：spawn_subagents 用 Promise.all(TS) / ThreadPoolExecutor(Python) 并发
工具过滤：tools="read_file,grep,glob" 限制子代理可用工具
技能预加载：skill="code-review" 子代理启动前注入技能指引
进度显示：⚡ 派遣 N 个子代理... + └ [idx/total] ▶/✓ 实时状态
上下文隔离：子代理独立上下文，返回结果摘要，不污染主对话

🔌 MCP 服务器（预配置开箱即用）

安装后即可使用，无需手动配置：

MCP 服务器	工具数	用途	启动方式
chrome-devtools	29	浏览器导航/截图/DOM/性能分析	`npx` 自动下载
cua-driver	55	桌面截图/点击/键盘/应用管理/窗口控制	`cua-driver mcp`

# 用 MCP 控制桌面
ctx -q '用 cua-driver MCP 查看运行的应用和屏幕尺寸'

# 用 MCP 控制浏览器
ctx -q '用 chrome-devtools MCP 打开 example.com 并获取页面内容'

Agent 自主完成：发现 MCP 注册表 → 列出工具方法 → 选择合适工具 → 调用并获取结果 → 清理会话。

🧠 上下文管理优化

参数	值	说明
`max_result_chars`	50000	工具结果截断上限（1M 上下文模型下仅占 1.25%）
`compress_threshold`	6000	工具结果压缩阈值（绝大多数结果完整保留）
`compact_input_pct`	85%	上下文达 85% 时才触发 compact
`max_steps`	0（无限）	Agent 自主决定何时完成，循环检测防止卡死

🛡 验证策略（文本优先）

文本模型（DeepSeek/GLM）无法识别图片，Agent 优先使用文本验证：

页面验证：browser_snapshot() 获取页面文本（非截图）
服务验证：check_server_status() HTTP 健康检查（自动重试 3 次）
代码验证：run_shell_command 运行测试/编译
截图循环检测：连续截图 3+ 次自动注入警告

设计哲学

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  Think   │ →  │  Guard   │ →  │   Act    │ →  │ Reflect  │
│ (LLM流式)│    │(Policy)  │    │(Executor)│    │(步数收敛)│
└──────────┘    └──────────┘    └──────────┘    └──────────┘

原则	说明
Agent 自主决策	不注入行为指令，Agent 从工具结果中自行推理
完整中介	所有工具调用必经 PolicyEngine 4 级审计
Share-nothing 隔离	每实例独立 work_dir / executor / observer

项目结构

cortx/
├── src/                         # TypeScript 源码
│   ├── core/                    # 核心引擎 (loop, registry, types, skills, tool_context, policy, llm, hooks, memory_store)
│   ├── tools/                   # 工具模块 (11 文件: file, exec, net, memory, mcp, browser, proxy, subagent, git, office, skills)
│   └── cli/                     # CLI 入口 + 终端显示
│
├── python/cortex_agent/         # Python 源码
│   ├── cortex_agent.py          # Agentic Loop 核心引擎
│   ├── tools.py                 # 核心工具 (41)
│   ├── tools_mcp.py             # MCP 客户端 + 注册表 + 会话管理
│   ├── tools_browser.py         # CDP 浏览器 (导航等待+文本快照)
│   ├── tools_computer.py        # 桌面控制
│   ├── tools_network.py         # 代理/镜像
│   ├── tools_office.py          # Office 文档
│   ├── tools_rag.py             # RAG 知识检索
│   ├── skills.py                # 技能系统
│   ├── config.py                # 配置加载
│   └── main.py                  # CLI 入口
│
├── dist/                        # 编译产物 (npm 发布)
├── bin/                         # CLI 入口脚本
├── .cortx/                      # 项目配置 + skills (gitignored)
├── CORTEX.md                    # 项目知识库
├── PUBLISH.md                   # 发布指南
├── pyproject.toml               # Python 包配置
├── package.json                 # npm 包配置
└── tsconfig.json                # TypeScript 配置

REPL 命令

命令	功能
`/help`	显示帮助
`/context`	上下文容量 + 缓存命中率
`/tools`	列出所有工具
`/skills`	列出所有技能
`/skill <name>`	调用技能
`/mode [s\|a\|y]`	切换权限模式 (Shift+Tab)
`/model [pro]`	切换模型
`/memory`	查看记忆
`/sessions`	列出会话
`/trace` `/audit`	审计追踪
`@filename`	文件引用

权限模式

模式	行为
`standard` 🛡️	SAFE 自动 / WRITE 区内 / SYSTEM 需确认
`auto` ✏️	自动批准编辑 + SYSTEM 放行
`yolo` ⚠️	全部放行 (CI/CD)

License

MIT

Metadata

Release files for cortx 2.9.15

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cortx 2.9.15
File	Size	Uploaded	Provenance
cortx-2.9.15.tar.gz	160.2 kB	Aug 21, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for cortx 2.9.15
File	Interpreter	ABI	Platform	Reset
cortx-2.9.15-py3-none-any.whl 166.6 kB Aug 21, 2026 Without provenance	Python 3	none	any	Details

Total release size: 326.8 kB

Release files / cortx-2.9.15.tar.gz

Download URL	cortx-2.9.15.tar.gz
Size	160.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`995c30e9f9afa6e02bd9c0a1538514973d634983e9471000d4816bb678a8d383`
BLAKE2b-256 checksum How to use checksums	`c32ef5433ac0c9b8b023a601cd807d78effbc983a838003dbae7fb023ee2de2f`
Upload date	Aug 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.13`

Release files / cortx-2.9.15-py3-none-any.whl

Download URL	cortx-2.9.15-py3-none-any.whl
Size	166.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`ffe06de82f9f5f74d084e4904a3a984549e609a825062a84afd987c12d034c1c`
BLAKE2b-256 checksum How to use checksums	`eefb04006d4a77e017d6d57f310769e3c4436428affb8e6708b66d234747fe67`
Upload date	Aug 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.13`

Security for cortx 2.9.15

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.