LLM API 请求
├── system prompt
│   ├── S1  运行环境（OS / Shell / Locale / Home）
│   ├── S2  平台信息（Agent 名称 / 版本 / 日期）
│   ├── S3  用户信息（语言偏好）
│   ├── S4  项目信息（类型 / 包管理器 / Git / 框架检测）
│   ├── S5  核心人设（角色定义 / 行为约束 / 输出格式）
│   ├── S6  agents.md 项目上下文（根目录始终 + 子目录按需）
│   ├── S7  静态 Rules（always_apply = true）
│   ├── S8  Skills 注册表摘要（name + description + path）
│   ├── S9  MCP Server 使用说明（M4）
│   ├── S10 工具使用指南
│   └── S11 Session 状态（TODO 进度 / token 用量，M7）
│
├── tools（API tools 参数，不占 system prompt）
│   ├── 内置工具（Read / Write / Shell / Grep / Glob / Edit / Ls / Delete）
│   ├── MCP 工具（通过 pi-mcp-adapter 注册）
│   └── 插件工具（扩展注册）
│
└── messages
    ├── [历史轮次]
    └── [当前轮 user message]
        ├── U1 IDE 状态（M5）
        ├── U2 Git 状态（M5）
        ├── U4 动态 Rules（glob 匹配当前文件）
        ├── U5 @ 引用内容（M5）
        └── U6 用户原始输入

数据流

createGeneralAgentSession()
    │
    ├── loadRules({ cwd, agentDir })
    │     ├── global:  agentDir/rules/*.md
    │     └── project: cwd/.pi/rules/*.md
    │
    ├── createResourceLoader()
    │     ├── assembleSystemPrompt(S1-S5 + S7 + S10)
    │     ├── additionalSkillPaths:  [cwd/.pi/skills]
    │     └── additionalPromptTemplatePaths: [cwd/.pi/prompts]
    │
    └── resourceLoader.reload()
          ├── getAgentsFiles()  → S6 (buildSystemPrompt)
          ├── getSkills()       → S8 (buildSystemPrompt)
          └── getPrompts()      → Commands (InteractiveMode)

依赖栈

packages/ai              ← LLM 流式调用（Anthropic / OpenAI / Google / Bedrock / Mistral）
packages/agent           ← Agent 循环、steering、状态管理
packages/tui             ← 终端 UI 渲染
packages/coding-agent    ← 基础设施复用（工具、会话、扩展、Skills、压缩、认证）
packages/general-agent   ← 本包（infocycle）：分层 prompt 组装、Rules、Commands、通用配置

功能特性

内置工具

工具	说明
`read`	读取文件内容，支持 offset / limit 片段读取
`write`	写入 / 创建文件
`edit`	精确字符串替换编辑文件
`bash`	终端命令执行，支持前台 / 后台、工作目录指定
`grep`	基于正则的文件内容搜索，支持 glob 过滤和上下文行
`find`	按文件名模式递归搜索
`ls`	列出目录内容
`delete`	删除文件或空目录

所有工具默认启用，可通过 --tools 或 --no-tools 控制。

Rules 系统

Rules 定义 agent 的行为约束。支持两种触发模式：

模式	触发时机	注入位置
`always_apply: true`	会话创建时	System prompt S7 层
`globs: ["*/.ts"]`	当前操作文件匹配 glob	User message U4 层
仅 `description`	Agent 自行判断相关性	Agent 通过 Read 读取

Rule 文件格式（Markdown + YAML frontmatter）：

---
description: "TypeScript 代码规范"
globs: ["**/*.ts", "**/*.tsx"]
always_apply: false
---
- 使用 ESM 模块语法，禁止 require()
- 函数参数超过 3 个时使用对象解构
- 优先使用 interface 而非 type alias

加载路径（project 同名文件覆盖 global；兼容 Claude Code / Cursor 目录）：

级别	路径
Global	`~/.pi/agent/rules/*.md`
兼容全局	`~/.claude/rules/`、`~/.cursor/rules/`
兼容项目	`cwd/.claude/rules/`、`cwd/.cursor/rules/`
Project	`cwd/.pi/rules/*.md`

Skills 系统

Skills 是可复用的专家知识包。启动时只加载摘要（name + description）到 S8 层，agent 按需通过 Read 工具读取 SKILL.md 全文。

用户: "帮我 review 这个 PR"
  → Agent 匹配到 code-review skill（基于 S8 摘要）
  → Agent 调用 Read("~/.pi/agent/skills/code-review/SKILL.md")
  → SKILL.md 全文进入 context，Agent 按指令执行

Skills 目录（兼容 Claude Code / Cursor）：

级别	路径
Global	`~/.pi/agent/skills/<name>/SKILL.md`
兼容全局	`~/.claude/skills/`、`~/.cursor/skills/`
兼容项目	`cwd/.claude/skills/`、`cwd/.cursor/skills/`
Project	`cwd/.pi/skills/<name>/SKILL.md`

Commands（斜杠命令）

Commands 是用户通过 / 触发的 prompt 模板。输入 / 时展示可用命令列表，选中后展开模板。

Command 文件格式：

---
description: 对当前文件进行代码审查
---
请对以下代码进行审查，关注正确性、性能、安全和可读性。

$CURRENT_FILE

变量替换：

变量	说明
`$CURRENT_FILE`	当前打开文件的内容
`$FILE_PATH`	当前文件路径
`$SELECTION`	当前选中文本
`$GIT_DIFF`	未提交的 diff
`$PROJECT_ROOT`	项目根路径
`$1`, `$2`, `$@`	命令参数（由 InteractiveMode 处理）

Commands 目录（兼容 Claude Code 的 commands/、Cursor 的 prompts/ 或 commands/）：

级别	路径
Global	`~/.pi/agent/prompts/*.md`
兼容全局	`~/.claude/commands/`、`~/.claude/prompts/`、`~/.cursor/commands/`、`~/.cursor/prompts/`
兼容项目	`cwd/.claude/commands/`、`cwd/.cursor/prompts/` 等
Project	`cwd/.pi/prompts/*.md`

M5 用户体验增强

@ 引用解析：用户消息中的 @file、@folder、@url 自动解析并注入 <referenced_content> 块
U1-U6 结构化 user message：IDE 状态（cwd、打开文件、选中文本）、Git 状态（分支、ahead/behind、staged/unstaged）、动态 Rules、@ 引用内容、用户原始输入
Diff 预览与斜杠命令：Write/Edit 操作前展示 diff，输入 / 展示可用命令列表（复用 upstream InteractiveMode）

agents.md 项目上下文

在项目根目录放置 AGENTS.md 或 CLAUDE.md，内容自动注入 S6 层。子目录同名文件在操作该目录文件时按需叠加。用于向 agent 提供项目背景、编码规范、目录结构等。

MCP 集成

通过 pi-mcp-adapter 扩展默认启用 MCP 支持。MCP 工具自动注册到 agent 可用工具列表中。配置从 infocycle 及兼容目录加载并合并：

级别	路径
Global	`~/.pi/mcp.json`
兼容全局	`~/.claude/mcp.json`、`~/.cursor/mcp.json`
兼容项目	`cwd/.claude/mcp.json`、`cwd/.cursor/mcp.json`
Project	`cwd/.pi/mcp.json`

项目配置中同名 server 覆盖全局，合并结果在会话创建时注入 pi-mcp-adapter。

M6 安全与稳定

功能	说明
循环检测/熔断	滑动窗口检测重复 tool 调用，超阈值自动熔断
操作确认	delete 始终确认；bash 匹配危险命令（rm -rf、sudo、dd 等）时需确认
路径白名单	文件操作限制在项目目录内，防止 `..` 逃逸
LLM 限流	RPM/TPM 滑动窗口，支持 block/reject 模式
结构化日志	console/json/custom 输出，level 过滤

M7 Token 管理

功能	说明
Token 预算管理器	分区预算跟踪与裁剪，超出时按策略截断
对话历史裁剪	大段 tool_result 截断为占位符，减少 context 占用
S11 Session 状态	TODO 进度、token 用量、会话时长注入 system prompt
ContextAssembler 集成	组装时检查各层 token 预算，超出时裁剪

安装

npm install infocycle

要求 Node.js >= 20.0.0。

配置

目录结构

除 .pi/ 外，infocycle 兼容 Claude Code（.claude/）和 Cursor（.cursor/）的目录约定，会按优先级发现并加载 skills、commands/prompts、rules、MCP 配置。详见 docs/tech/compat-resource-paths.md。

~/.pi/agent/           # 全局配置目录（INFOCYCLE_AGENT_DIR）
├── rules/                    # 全局 Rules
│   └── git-safety.md
├── skills/                   # 全局 Skills
│   └── code-review/
│       └── SKILL.md
├── prompts/                  # 全局 Commands
│   └── review.md
├── auth.json                 # API key 凭证存储
├── settings.json             # 全局设置
└── models.json               # 自定义模型 / Provider 配置

cwd/.pi/               # 项目级配置
├── rules/                    # 项目 Rules（覆盖同名全局 rule）
│   └── typescript.md
├── skills/                   # 项目 Skills
├── prompts/                  # 项目 Commands
└── mcp.json                  # MCP Server 配置

settings.json

全局（~/.pi/agent/settings.json）和项目级（cwd/.pi/settings.json）均可配置，project 覆盖 global。

{
  // 全局 API 代理：所有 Provider 的请求都走这个地址
  "baseUrl": "https://my-proxy.example.com/v1",

  // 默认 Provider 和模型
  "defaultProvider": "openai",
  "defaultModel": "gpt-4o",

  // 思考级别: off / minimal / low / medium / high / xhigh
  "defaultThinkingLevel": "medium",

  // 其他设置继承自 pi-coding-agent 的 Settings（theme, compaction, retry 等）
}

baseUrl 字段会覆盖所有已注册 Provider 的 API 端点。适用于通过统一代理（如 one-api、litellm）转发请求的场景。如需细粒度的 Provider 配置（不同 Provider 不同地址、自定义模型），使用 models.json。

auth.json

位于 ~/.pi/agent/auth.json，存储 API key 凭证：

{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "openai": { "type": "api_key", "key": "sk-..." }
}

配置优先级

配置项	优先级（高 → 低）
模型选择	`--model` CLI → `INFOCYCLE_DEFAULT_MODEL` 环境变量 → `settings.json` `defaultProvider`/`defaultModel`
Base URL	`INFOCYCLE_BASE_URL` 环境变量 → 项目 `settings.json` `baseUrl` → 全局 `settings.json` `baseUrl`
API Key	`--api-key` CLI → `auth.json` → 环境变量（`ANTHROPIC_API_KEY` 等） → `models.json` provider `apiKey`

models.json

位于 ~/.pi/agent/models.json，用于注册自定义 Provider 或覆盖内置 Provider 的 baseUrl：

{
  "providers": {
    // 覆盖 OpenAI 的 baseUrl
    "openai": {
      "baseUrl": "https://my-openai-proxy.com/v1"
    },
    // 注册自定义 Provider + 模型
    "my-local": {
      "baseUrl": "http://localhost:11434/v1",
      "apiKey": "MY_LOCAL_KEY",
      "api": "openai-completions",
      "models": [
        {
          "id": "llama3",
          "reasoning": false,
          "input": ["text"],
          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
          "contextWindow": 8192,
          "maxTokens": 4096
        }
      ]
    }
  }
}

settings.json 中的 baseUrl 优先级高于 models.json 中的 Provider baseUrl（因为 settings 在 models 加载后覆盖）。

环境变量

变量	说明	默认值
`ANTHROPIC_API_KEY`	Anthropic Claude API key	-
`OPENAI_API_KEY`	OpenAI GPT API key	-
`GEMINI_API_KEY`	Google Gemini API key	-
`INFOCYCLE_DEFAULT_MODEL`	默认模型，支持 `provider/model` 格式	-
`INFOCYCLE_BASE_URL`	全局 API 代理地址	-
`INFOCYCLE_AGENT_DIR`	全局配置目录	`~/.pi/agent`

与 pi-coding-agent 的区别

项目	pi-coding-agent	infocycle
配置目录	`.pi/`	`.pi/`
全局目录	`~/.pi/agent/`	`~/.pi/agent/`
环境变量	`PI_CODING_AGENT_DIR`	`INFOCYCLE_AGENT_DIR`
默认人设	编码助手	通用 AI 助手
Rules 系统	无	always_apply + glob 匹配
MCP	可选	默认启用
CLI 命令	`pi`	`infocycle`

CLI 使用

交互模式

infocycle

启动全功能终端交互界面，支持多轮对话、工具调用、会话管理。

单次执行模式

infocycle -p "列出当前目录所有 TypeScript 文件"
infocycle -p "分析 package.json 中的依赖关系"

处理完毕后退出，适合脚本和 CI/CD 场景。

完整参数

infocycle [options] [messages...]

选项:
  --model <pattern>              模型 ID（支持 "provider/id" 格式）
  --provider <name>              Provider 名称
  --api-key <key>                API key（默认从环境变量获取）
  --system-prompt <text>         覆盖 system prompt
  --append-system-prompt <text>  追加到 system prompt
  --thinking <level>             思考级别: off, minimal, low, medium, high, xhigh
  --mode <mode>                  输出模式: text（默认）, json
  --print, -p                    单次执行模式
  --continue, -c                 继续上次会话
  --resume, -r                   选择历史会话恢复
  --session <path>               使用指定会话文件
  --no-session                   临时会话（不保存）
  --models <patterns>            逗号分隔的模型列表（循环使用）
  --tools <tools>                逗号分隔的工具列表
  --no-tools                     禁用所有内置工具
  --verbose                      详细启动输出
  --offline                      禁用启动时的网络操作
  --help, -h                     显示帮助
  --version, -v                  显示版本号

使用示例

# 指定模型
infocycle --model anthropic/claude-sonnet-4-20250514 "帮我优化这段代码"

# 启用高级思考
infocycle --thinking high

# 只启用部分工具
infocycle --tools read,grep,bash

# 继续上次对话
infocycle -c "我们刚才讨论的问题解决了吗?"

# JSON 输出模式（适合管道处理）
infocycle --mode json -p "列出项目依赖"

SDK 编程接口

import {
  createGeneralAgentSession,
  type CreateGeneralAgentSessionOptions,
} from "infocycle";

const { session, rules, modelFallbackMessage } =
  await createGeneralAgentSession({
    cwd: process.cwd(),
    // model, tools, resourceLoaderOptions 等可选配置
  });

// 使用 session 进行交互
const result = await session.prompt("列出当前目录的文件");

核心导出

导出	说明
`createGeneralAgentSession()`	创建 agent 会话，返回 session + 已加载的 rules
`assembleSystemPrompt()`	组装 S1-S5 + S7 + S10 各层 prompt
`formatStaticRules()`	格式化 always_apply rules 为 XML
`loadRules()`	加载两级 rules（global + project）
`matchDynamicRules()`	用 glob 匹配动态 rules
`substituteVariables()`	命令变量替换
`generalTools`	所有内置工具实例数组
`allGeneralTools`	按名称索引的工具映射

开发

# 编译
npm run build

# 监听模式
npm run dev

# 类型检查 + lint（从仓库根目录）
npm run check

# 运行测试（从包目录）
npx tsx ../../node_modules/vitest/dist/cli.js --run

# 单次执行测试
node dist/main.js -p "你好"

里程碑进度

里程碑	状态	说明
M0 项目脚手架	done	包结构、tsconfig、入口文件
M1 最小可运行 Agent	done	CLI、工具集、session 创建
M2 完整 Prompt 组装	done	S1-S5 + S10 分层组装
M3 文档加载系统	done	Rules、Skills 路径、Commands 变量替换
M4 MCP 集成	done	pi-mcp-adapter 默认启用
M5 用户体验增强	done	@ 引用、U1-U6 消息组装、diff 预览、斜杠命令 UI
M6 安全与稳定	done	循环检测/熔断、操作确认、路径白名单、LLM 限流、结构化日志
M7 Token 管理	done	分区预算、历史裁剪、S11 状态注入
M8 配置与认证	-	三级配置、Undo/Redo

详细计划见 docs/plan.md。

Keywords

FAQs

What is infocycle?

Is infocycle well maintained?

Package last updated on 10 Mar 2026

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

infocycle