English ｜简体中文

官网｜快速开始｜四层设计｜文档｜设计说明｜扩展｜社区｜贡献｜ Issues

Cortico 是基于事件流系统设计的 Agent Harness，用于自主响应、持续运行、混合实时输入场景的智能体开发，适用于人格 Bot、AI 主播、角色扮演、聊天陪伴等多种下游任务。Cortico Bot 远不只是聊天 Bot：得益于围绕事件流设计的 Agent 系统，Cortico 可以帮助构建长期持续存在、适用于复杂输入的 AI 智能体，它支持自由的外部扩展，能够同时观察和操作多个外部环境，包括聊天平台、实时游戏、甚至现实环境。Cortico 的目标是：把你的 AI 带到这个世界！（Bring your AI to the world！） **语言**：WebUI 有简体中文、繁體中文、English、日本語、한국어、Français、Deutsch、Español (Latinoamérica)、Português (Brasil)、Italiano、Русский 11 种语言。WebUI 语言不改变模型读到的内容；Core 写进模型上下文的文本是英文。 ## 特性 1. 🆓 免费开源！ 2. 🤖 原生 Agent Harness，一切围绕 Agent 设计。 3. 🔌 模块化的 LLM Provider 组件，内部使用 Responses 协议，对外支持多种上游 LLM API，并支持使用本地部署模型。 4. 🧠 自由的内部上下文管理，支持不同的 AI 智能体行为模式，兼容多种 Memory 系统设计。 5. 🧩 外部环境（Cortico World）与内部隔离，采用事件投递／工具调用作为输入／输出，提供优秀的兼容性和近乎无限的可扩展能力。 6. 🖥️ 提供便于操作的 WebUI 支持。 7. 🪄 提供专用于 AI 开发的 Extension Creator 系统（[Cortina](https://github.com/Pal-AI-Lab/Cortina)），非专业开发者也可以使用 AI Agent 快速创建想要的扩展，或迁移现有的实现到 Cortico！ ## 用 Cortico 创造 AI VTuber 使用 [cortico-world-vtuber](https://github.com/Pal-AI-Lab/cortico-world-vtuber) 立刻开始创造你的 AI VTuber：经 VTube Studio 驱动 Live2D 模型、流式 TTS 出声、强制对齐器给字幕定时、overlay 画面推进 OBS，作为一个 Cortico World 整体提供。它遵循独立的源码协议（AGPL-3.0 + CLA），因此以独立仓库发布，不在 Cortico 主干上。 ## 用 Cortina 编写扩展使用

快速完成你想要的 Cortico 扩展和适配！如何使用：首先，从 [https://github.com/Pal-AI-Lab/Cortina](https://github.com/Pal-AI-Lab/Cortina) 克隆仓库到本地。 1. 用任意 Coding Agent 打开该工作区。 2. 对它说你好！Cortina 会用对话的方式协助并指引你完成你想要的 Cortico 扩展开发 / 适配！ 3. 不需要写代码的经验或者知识也可以轻松使用！ 4. 完成扩展之后，可以发布到 npm 以共享给其他人~ npm 上带 `cortico-world`、`cortico-provider` 或 `cortico-bot` 关键字的包会列在 WebUI 的「扩展」页，显示 npm 统计的累计、近 30 天、近 7 天下载量。 _{Cortina 基于 Pal AI Lab 提出的 [TINA（There Is No App）Spec](https://github.com/Pal-AI-Lab/ThereIsNoApp) 设计。这里没有 APP：语言即代码，Agent 即 Runtime。} ## 快速开始运行环境需 Node 22+。 ```bash corepack pnpm install pnpm start ``` ### 1. 首次启动与 WebUI 引导首次启动且未检测到已有部署时，启动器会自动创建名为 `mybot` 的默认部署（基于参考实现 `cormini`，默认启用控制台对话），并自动启动 WebUI 服务： **`http://127.0.0.1:7788/`** 在 WebUI 的控制台页面中，开场引导将协助你完成三项基础配置：配置语言模型端点、查看已挂载的 World、调整系统提示词。配置好可用端点后，点击「打个招呼」即可让 Bot 主动开口交流。模型端点、API 密钥与运行参数均可在 WebUI 中可视化修改，保存后下一次请求生效；托管运行时的启动参数在它下一次启动时生效。 WebUI 的初始语言依次取 `config.json` 的 `language`、`CORTICO_LANGUAGE`、系统区域（读不到区域时用简体中文）。在「设置 → 通用」里切换，只对当前浏览器生效，不用重启 bot。 ### 2. 多部署管理每个部署对应 `deployments/` 下的一个独立子目录（详见 [deployment.md](docs/deployment.md)）。再建一份： ```bash pnpm start --new ``` 依次选择 bot 代码包、部署目录名与展示名称，建好后直接启动，端点等其余配置在 WebUI 中完成。按名称启动指定部署： ```bash pnpm start second ``` 启动脚本（`pnpm start`、`./start.sh` 或 Windows 上的 `start.bat`）会自动安装缺失依赖、在 WebUI 前端产物缺失或落后于源码时构建，在交互式命令行中列出全部部署供选择（含新建部署入口），并在 WebUI 请求重启时自动重启守护进程。 ## 四层设计 Cortico 采用严格解耦的四层架构设计： | 层级 | 核心职责 | 所在路径 | |---|---|---| | **Core** | 管理会话（Session）、事件流分发与模型调用生命周期；内部无业务语义。 | `src/core/` | | **Persona** | 定义一类 Bot 的核心语义：上下文构造、认知循环与对 Memory 的读写协议。 | `bots/<名称>/persona/` | | **Memory** | Bot 内部持久化状态的唯一权威载体，结构与组织形态由 Persona 决定。 | `<部署>/memory/` | | **World** | 与单个外部环境交互的隔离边界：处理环境事件输入、工具声明与环境提示词。 | `src/worlds//` | | **Bot** | 部署装配定义：将一个指定的 Persona 与一组 World 组装成可运行实例。 | `bots/<名称>/index.ts` | ## 文档 | 页面 | 内容索引 | |---|---| | [deployment.md](docs/deployment.md) | 部署目录结构、部署根路径与启动器工作机制 | | [configuration.md](docs/configuration.md) | 四层配置合并规则、配置组定义与参数热更新 | | [providers.md](docs/providers.md) | Provider 模块、模型目录、端点配置与计费策略 | | [runtimes.md](docs/runtimes.md) | `llamacpp` 本机运行时管理与模型文件配置 | | [webui.md](docs/webui.md) | WebUI 架构、运行时监控与各模块页面声明 | | [sessions.md](docs/sessions.md) | Session 生命周期、上下文容量调度与交接机制 | | [runs.md](docs/runs.md) | 运行记录目录、日志结构与 `pnpm logq` 检索工具 | | [personas.md](docs/personas.md) | Persona 生命周期钩子、Memory 架构与装配机制 | | [worlds.md](docs/worlds.md) | World 交互契约：事件投递、工具执行与环境提示词 | | [world-compatibility.md](docs/world-compatibility.md) | 其他架构的 bot 挂载 Cortico World 的兼容等级与对照表 | | [extensions.md](docs/extensions.md) | 扩展包规范、Manifest 定义与动态加载器 | | [environment-variables.md](docs/environment-variables.md) | `CORTICO_*` 环境变量规范与三层 `.env` 文件继承 | | [windows.md](docs/windows.md) | Windows 环境兼容性与运行说明 | | [development.md](docs/development.md) | 常用开发命令、双 tsconfig 架构与测试体系布局 | ## 内建 World | World | ID | 接入环境与能力 | |---|---|---| | 控制台对话 | `console` | WebUI 内建的对话页，支持双向文字会话 | | QQ | `qq` | 接入 QQ 群聊与私聊，支持可选的多模态视觉模型图像理解 | | 哔哩哔哩直播 | `bilibili` | 实时监听弹幕、礼物、醒目留言（SC）、大航海、进场通知与人流指标，附带本机 OBS 画面 Overlay | | Minecraft | `minecraft` | 基于 Mineflayer 接入 Minecraft 原版服务器，实现文字环境观察与高层动作执行 | | 网页搜索 | `websearch` | 通过 Brave Search API 或 DeepSeek 搜索 API 检索实时网络信息;两家的地址都可换成兼容的代理 | 每次发版还把 `minecraft`、`qq`、`bilibili`、`websearch` 以 `cortico-world-` 发到 npm，版本与框架相同，供不内建这些 World 的应用安装。框架里已有同 id 的 World 时，装上的包不加载。 ## 模型端点 | Provider | 适配模型服务 / 说明 | |---|---| | `openai-responses-compat` | 支持 Responses API 协议规范的模型服务与兼容网关 | | `llamacpp` | 本机 `llama-server` 运行时集成，支持官方 Binary 自动下载与子进程生命周期托管 | 如需接入更多模型协议与供应商，可通过扩展系统无缝安装。 ## 社区加入我们的群组咨询项目进展，和其他开发者交流！ * QQ 群：681195563 * Discord Server：https://discord.gg/DR37WB5zJf ## 参与贡献欢迎提交 Issue 与 Pull Request！ * 提交前请查阅 [CONTRIBUTING.md](CONTRIBUTING.md)（了解仓库边界与扩展开发规范）以及 [AGENTS.md](AGENTS.md)（代码审查清单）。 * 欢迎使用 AI 编码助手辅助开发，但贡献者必须能够清晰解释提交的所有代码逻辑。 * WebUI 文案放在 `strings.ts`（`zh`、`en` 两版是全的），其余语言各写在旁边的 `strings.<语言代码>.ts`；译文缺的键，`zh-Hant` 读 `zh`，其余读 `en`。详见 [webui.md](docs/webui.md#语言) 的「语言」一节。 * 提交 PR 前请确保自动化校验通过： ```bash pnpm test pnpm run typecheck ``` 若涉及 WebUI 前端代码改动，需额外执行： ```bash pnpm typecheck:web pnpm build:web ``` ## 范例实现如果你使用 Cortico 构建了有趣的 Bot，欢迎提交 PR 收录到这里！ * [@可缇Corti](https://space.bilibili.com/3707044056009191) — 来自未来的 AI VTuber。 * ...持续更新中！