Skip to content

iodone/philip

BranchesTags

Repository files navigation

Philip

Philip 是 Bub 生态的主入口项目，提供两部分能力：

  1. Bub Distribution — 多渠道 AI Agent 网关，支持飞书、Telegram、微信、JSON-RPC，通过 boxsh 沙箱隔离执行。负责启动、沙箱管理和 plugin 组装。
  2. CLI Capabilities — 命令行工具集，管理 Bub workspace，并提供 gateway 本地联调 client。当前重点是 wiki 和 rpc chat：wiki 负责 workspace 初始化、知识库搜索、图分析、同步；rpc chat 用于验证 JSON-RPC channel 的会话与流式行为。

项目结构

philip/
├── src/
│   └── philip/                  # Python 包
│       ├── capabilities/       # CLI 能力模块
│       │   └── wiki/           # 知识库管理
│       ├── channels/           # Bub Channel 插件
│       │   └── jsonrpc_channel.py  # JSON-RPC 2.0 通道
│       ├── cli/                # CLI 入口（rub standalone_cli）
│       ├── plugins/            # Bub 插件
│       ├── server/             # JSON-RPC 服务端实现
│       └── skills/             # 内置 agent skill
├── tests/                      # 单元测试
├── docs/                       # 详细文档
│   ├── DOCKER_USAGE.md         # Docker 部署指南
│   ├── JSONRPC_CHANNEL.md      # JSON-RPC 通道 API 文档
│   └── WIKI.md                 # Wiki CLI 详细用法
├── run-host.sh                 # 宿主机模式启动脚本
├── entrypoint.sh               # Docker 容器入口
├── docker-compose.yml          # Docker 模式编排
├── Dockerfile                  # 容器镜像定义
├── .env.example                # 配置模板
├── pyproject.toml              # Python 依赖
└── AGENTS.md                   # Agent 运行规则

安装

CLI 工具（推荐）

使用 pipx 安装 philip CLI，命令会注册到系统 PATH，agent 和 bash 脚本可直接调用：

pipx install git+https://github.com/iodone/philip.git

安装后即可在任意目录使用：

philip wiki.init directory=/path/to/workspace
philip wiki.search query="agent architecture"
philip wiki.sync
philip rpc.chat -h

从源码开发

git clone https://github.com/iodone/philip.git
cd philip
uv sync

快速开始

1. 初始化 Wiki Workspace

使用 philip wiki.init 初始化一个 workspace。创建完整目录结构、模板文件，并自动将内置 skill 安装到 .agents/skills/：

philip wiki.init directory=/path/to/workspace

初始化后的 workspace 结构：

/path/to/workspace/
├── AGENTS.md               # Agent session 入口协议
├── README.md               # Workspace 总览
├── rules/
│   ├── SOUL.md             # Agent 身份定义
│   ├── USER.md             # 用户偏好与原则
│   ├── COMMUNICATION.md    # 协作方式
│   ├── SECURITY.md         # 安全规则
│   ├── WORKSPACE.md        # 目录路由速查
│   ├── axioms/             # 稳定判断规则
│   └── skills/             # Skill 索引
├── .agents/skills/
│   └── workflow-llm-wiki/SKILL.md  # 内置 wiki 操作 skill
├── contexts/               # 输入层（ingest 材料）
│   ├── blog/               # 博客草稿
│   ├── clippings/          # 外部原始资料
│   ├── daily_records/      # 日级记录
│   ├── life_record/        # 生活观察
│   ├── survey_sessions/    # 调研过程
│   └── thought_review/     # 深度分析
├── wiki/
│   ├── pages/              # Wiki 页面（Obsidian 兼容）
│   ├── wiki-purpose.md     # Wiki 目的与范围
│   ├── wiki-schema.md      # 页面规范
│   ├── wiki-agent.md       # Agent 行为规则
│   └── wiki-log.md         # 操作日志
└── .llm-wiki/
    └── config.toml         # Vault 配置

2. 配置并启动 Bub 网关

Bub distribution 部分需要从源码运行：

cp .env.example .env
# 编辑 .env，填入 BUB_MODEL、BUB_API_KEY、BUB_WORKSPACE（指向上面的 workspace）

# 宿主机开发模式（无 sandbox）
uv run bub -w /path/to/workspace gateway

# 宿主机隔离模式（boxsh sandbox）
./run-host.sh

# 或容器部署模式
docker-compose up -d

启动后，agent 会自动读取 workspace 中的 wiki skill，通过 philip wiki.search/wiki.graph/wiki.sync 等命令管理知识库。

3. 验证 JSON-RPC Channel

JSON-RPC 通道不是单独启动的服务，而是 Bub gateway 自动加载的 channel 插件。要启用它，先打开环境变量开关：

export BUB_JSONRPC_ENABLE=true

然后统一通过 gateway 启动：

uv run bub -w /path/to/workspace gateway

启动后默认监听：

  • POST http://127.0.0.1:8420/rpc
  • GET ws://127.0.0.1:8420/ws

从源码仓库内联调时，推荐直接使用 repo 环境里的 CLI：

uv run philip rpc.chat
uv run philip rpc.chat ws=true stream=true
uv run philip rpc.chat session=demo-session

如果你已经通过 pipx 安装了最新 CLI，也可以直接使用：

philip rpc.chat

CLI Capabilities

Wiki

命令 说明
philip wiki.init <dir> 初始化 workspace（目录结构 + 模板 + skill）
philip wiki.search <query> BM25 搜索（配置 DB9 后自动启用向量 + RRF 融合）
philip wiki.sync 变更检测（mtime + SHA-256），可选推送到 DB9
philip wiki.graph 链接图分析：社区发现、hub 页、orphan 页、wanted 页
philip wiki.status wiki 健康概览

详细用法见 docs/WIKI.md。

JSON-RPC

命令 说明
philip rpc.chat 交互式 REPL 客户端（HTTP 模式）
philip rpc.chat ws=true WebSocket 模式
philip rpc.chat ws=true stream=true 流式输出模式
philip rpc.chat session=<id> 指定 session ID

JSON-RPC 通道作为 Bub gateway 插件自动加载，支持 HTTP (POST /rpc) 和 WebSocket (GET /ws) 两种传输方式。适合本地调试、CLI 交互和外部系统集成。

协议约束：

  • session_id 是业务会话键，对应 Bub tape/chat
  • JSON-RPC 顶层 id 只做单次 request correlation
  • 同一个 session_id 支持并发 unary chat.send
  • 同一个 session_id 的并发 chat.stream 会被显式拒绝，避免隐式覆盖

启用开关：

  • BUB_JSONRPC_ENABLE=true：启用 JSON-RPC channel
  • 兼容别名：BUB_JSONRPC_ENABLED=true
# 快速测试
curl -s http://localhost:8420/rpc \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"1","method":"chat.send","params":{"session_id":"test","message":"hello"}}'

详细 API 文档见 docs/JSONRPC_CHANNEL.md。

配置

通用配置

配置项 说明 必需
BUB_MODEL LLM 模型，格式 provider:model_id ✅
BUB_API_KEY API 密钥 ✅
BUB_API_BASE API 端点（自定义模型时使用） ❌
BUB_WORKSPACE Agent 工作空间路径 ✅

飞书

配置项 说明 必需
BUB_FEISHU_APP_ID 应用 App ID ✅
BUB_FEISHU_APP_SECRET 应用 App Secret ✅
BUB_FEISHU_VERIFICATION_TOKEN Webhook 验证 Token ❌
BUB_FEISHU_ENCRYPT_KEY Webhook 事件加密密钥 ❌
BUB_FEISHU_ALLOW_USERS 允许的用户 open_id，逗号分隔 ❌
BUB_FEISHU_ALLOW_CHATS 允许的 Chat ID，逗号分隔 ❌
BUB_FEISHU_BOT_OPEN_ID 机器人 open_id，用于群聊 @检测 ❌
BUB_FEISHU_BOT_NAME 机器人显示名称，用于 @名称 匹配 ❌

Telegram

配置项 说明 必需
BUB_TELEGRAM_TOKEN Bot Token（@BotFather 获取） ✅
BUB_TELEGRAM_ALLOW_USERS 允许的用户 ID，逗号分隔 ❌
BUB_TELEGRAM_ALLOW_CHATS 允许的 Chat ID，逗号分隔 ❌

微信

配置项 说明 必需
WEIXIN_BASE_URL 微信 API 基础地址 ❌
WEIXIN_ACCOUNT_ID 微信账号 ID ❌

文档

License

MIT

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

4 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages