pipiclaw

Pipiclaw 是一个 AI 智能体，把 pi-coding-agent 带到钉钉对话里，支持过程性 AI 卡片、最终 Markdown 回复、内置 Slash 命令、技能扩展和定时事件。

功能

• 钉钉 Stream 模式接收消息，自动重连
• 过程性思考和执行信息通过 AI Card 展示，最终答复独立快速返回
• 内置 Slash 命令：/help、/new、/compact、/session、/model
• 忙碌时默认将普通新消息作为 steer 送入当前任务，也支持显式 /steer、/followup、/stop
• 每个 DM / 群聊独立工作空间
• 支持 workspace 级 SOUL.md、AGENTS.md、MEMORY.md
• 支持全局和频道级技能目录
• 支持 runtime-managed 的频道级 MEMORY.md / HISTORY.md
• 支持 immediate / one-shot / periodic 定时事件
• 支持自定义模型配置和模型切换

安装

npm install -g @oyasmi/pipiclaw

首次运行

pipiclaw

首次运行时，Pipiclaw 会自动创建 ~/.pi/pipiclaw/，并生成这些文件和目录：

• channel.json
• auth.json
• models.json
• settings.json
• workspace/
• workspace/events/
• workspace/skills/
• workspace/SOUL.md
• workspace/AGENTS.md
• workspace/MEMORY.md

如果 channel.json 还是示例占位符，程序会提示你先填写真实配置，然后退出。

钉钉应用配置

在 钉钉开放平台 创建企业内部应用：

1. 创建应用并获取 Client ID 和 Client Secret
2. 开启机器人能力并启用 Stream 模式
3. 如需 AI Card 流式输出，创建 AI 卡片模板并获取 Card Template ID

配置文件

channel.json

~/.pi/pipiclaw/channel.json

程序会自动生成一个模板文件。你需要至少填写：

• clientId
• clientSecret

通常还会填写：

• robotCode
• cardTemplateId
• allowFrom

模板示例：

{
  "clientId": "your-dingtalk-client-id",
  "clientSecret": "your-dingtalk-client-secret",
  "robotCode": "your-robot-code",
  "cardTemplateId": "your-card-template-id",
  "cardTemplateKey": "content",
  "allowFrom": ["your-staff-id"]
}

说明：

• robotCode 留空时默认回退到 clientId
• cardTemplateId 留空时不使用 AI Card 流式输出
• allowFrom 设为 [] 或删除时允许所有人

auth.json

~/.pi/pipiclaw/auth.json

首次运行会自动生成空对象：

{}

如果你使用环境变量提供模型密钥，可以一直保持为空。也可以手工写成：

{
  "anthropic": "your-anthropic-api-key"
}

models.json

~/.pi/pipiclaw/models.json

首次运行会自动生成最小合法空配置。你需要在 providers 下面自己添加自定义 provider 和模型定义：

{
  "providers": {}
}

如果你不需要自定义模型，可以一直保持这个空配置。

settings.json

~/.pi/pipiclaw/settings.json

首次运行会自动生成：

{}

/model 等命令写入的默认模型会保存在这里，并在重启后继续生效。

运行

填写好 channel.json 和模型认证信息后，再次启动：

pipiclaw

如需 Docker sandbox，可以显式指定：

pipiclaw --sandbox=docker:your-container

内置 Slash 命令

Pipiclaw 暴露两层命令：

• transport 层命令：由 DingTalk runtime 直接处理
• session 层命令：由 AgentSession extension command 立即执行，不作为普通 prompt 发给模型

空闲时可用

• /help 显示帮助
• /new 开启新会话
• /compact [instructions] 手动压缩当前会话上下文
• /session 查看当前会话状态、消息统计、token 使用和模型信息
• /model [provider/modelId|modelId] 查看当前模型，或用精确匹配切换模型

说明：

• /model 无参数时返回当前模型和可用模型列表
• /model <ref> 只支持精确匹配

忙碌时可用

• 普通消息 默认按 steer 处理，在当前工具步骤结束后尽快转向
• /help 显示帮助
• /stop 停止当前任务
• /steer <message> 显式指定一次 steer，改变当前任务方向
• /followup <message> 将一条新请求排到当前任务完成之后再执行

说明：

• busy 时普通消息默认等价于 /steer <message>
• /steer 更适合纠偏、补充限制条件、修改当前任务方向
• /followup 更适合“等这件事做完，再继续做下一件事”
• busy 时，其他 slash 输入不会执行；只允许 /help、/stop、/steer、/followup

Workspace Files

Pipiclaw 只会自动识别并使用下面这些 workspace 文件或目录：

• SOUL.md
• AGENTS.md
• MEMORY.md
• skills/
• events/

TOOLS.md 当前不受支持。即使你手工创建了它，也不会被自动加载或生效。

Global And Channel Scope

Pipiclaw 同时支持：

• 全局 workspace 文件：~/.pi/pipiclaw/workspace/
• 渠道级文件：~/.pi/pipiclaw/workspace/dm_xxxx/ 或 group_xxxx/

它们的关系如下：

File Intent

• SOUL.md 定义 Pipiclaw 的身份、语气、默认语言和回复风格。它会追加到 pi 默认底座 prompt 之后。首次运行生成的只是说明模板，你需要替换成真实内容。
• AGENTS.md 定义行为规则、工具使用策略、安全约束和项目工作流。只读取 workspace 级文件。不要把 runtime 内建的记忆系统细节完整复制到这里。
• MEMORY.md 定义持久记忆。workspace 级文件适合存稳定共享背景，由管理员维护；channel 级文件适合存 durable facts、ongoing work、decisions、open loops，并由 runtime consolidation 自动维护。
• HISTORY.md 仅存在于 channel 目录。保存旧上下文的摘要历史，由 runtime consolidation 自动维护。
• skills/ 存放自定义技能。适合放可复用的 CLI 工具、脚本和 skill 说明。
• events/ 存放定时事件定义。只支持全局目录，不支持放到单个 channel 目录里。

工作空间布局

~/.pi/pipiclaw/
├── channel.json
├── auth.json
├── models.json
├── settings.json
└── workspace/
    ├── SOUL.md
    ├── AGENTS.md
    ├── MEMORY.md
    ├── skills/
    ├── events/
    └── dm_{userId}/
        ├── MEMORY.md
        ├── HISTORY.md
        ├── .channel-meta.json
        ├── context.jsonl
        ├── log.jsonl
        └── skills/

记忆模型

Pipiclaw 的默认 session 上下文只直接加载这些内容：

• pi 默认底座 system prompt
• workspace 级 SOUL.md
• workspace 级 AGENTS.md
• 内置工具说明
• workspace 和 channel 两层 skills 的摘要

这些文件不会默认直接进入上下文：

• workspace/MEMORY.md
• <channel>/MEMORY.md
• <channel>/HISTORY.md
• <channel>/log.jsonl
• <channel>/context.jsonl

说明：

• workspace/MEMORY.md 是稳定共享背景，由管理员维护，runtime 不会自动改写。
• <channel>/MEMORY.md 和 <channel>/HISTORY.md 由 runtime 在 compaction 或 session trimming 前自动 consolidation。
• agent 被鼓励在需要时主动读取 channel memory/history。
• log.jsonl 和 context.jsonl 是冷存储，只做原始归档，不承担记忆角色。
• channel 目录首次初始化时会立即创建 MEMORY.md 和 HISTORY.md，而不是等到首次 consolidation 再懒创建。

定时事件

在 ~/.pi/pipiclaw/workspace/events/ 中创建 JSON 文件来触发定时任务：

• immediate
• one-shot
• periodic

示例：

{
  "type": "periodic",
  "channelId": "dm_your-staff-id",
  "text": "Review your MEMORY.md files. Remove outdated entries, merge duplicates, ensure well-organized.",
  "schedule": "0 3 * * 0",
  "timezone": "Asia/Shanghai"
}

环境变量

开发

npm install
npm run check