infocycle

基于 pi-mono 基础设施构建的领域无关 AI Agent 框架。复用 pi-coding-agent 的工具链、会话管理和终端 UI，提供可配置的分层 Prompt 组装、Rules 系统、Skills 渐进加载和 MCP 集成。

系统架构

分层 Prompt 组装（S1 - S11）

每次 LLM API 调用时，system prompt 由 ContextAssembler 按层级组装：

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。