{"id":48800644,"url":"https://github.com/oyasmi/pipiclaw","last_synced_at":"2026-04-19T13:03:03.176Z","repository":{"id":348309001,"uuid":"1197432554","full_name":"oyasmi/pipiclaw","owner":"oyasmi","description":"An AI assistant runtime for coding and team workflows, with DingTalk AI Cards, sub-agents, memory, and scheduled events.","archived":false,"fork":false,"pushed_at":"2026-04-09T10:37:22.000Z","size":620,"stargazers_count":10,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-09T11:29:12.940Z","etag":null,"topics":["ai-agents","asistant","dingtalk","harness-engineering","llm"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@oyasmi/pipiclaw","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oyasmi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-31T15:19:39.000Z","updated_at":"2026-04-08T09:34:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/oyasmi/pipiclaw","commit_stats":null,"previous_names":["oyasmi/pipiclaw"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/oyasmi/pipiclaw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oyasmi%2Fpipiclaw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oyasmi%2Fpipiclaw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oyasmi%2Fpipiclaw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oyasmi%2Fpipiclaw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oyasmi","download_url":"https://codeload.github.com/oyasmi/pipiclaw/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oyasmi%2Fpipiclaw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32005831,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","asistant","dingtalk","harness-engineering","llm"],"created_at":"2026-04-14T02:03:46.606Z","updated_at":"2026-04-19T13:03:03.162Z","avatar_url":"https://github.com/oyasmi.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pipiclaw\n\nPipiclaw 是一个 AI 助手运行时（AI assistant runtime），以 [`pi-coding-agent`](https://www.npmjs.com/package/@mariozechner/pi-coding-agent) 为核心，补齐了作为工作助手长期使用时最需要的几层能力：钉钉接入、AI Card 过程展示、子代理、分层记忆、定时事件，以及按会话通道持久化的工作区（workspace）。\n\n如果你希望 AI 助手不只是聊天，而是能在钉钉里持续工作、保留上下文、执行任务，并且实时告知你它正在做什么，那么 Pipiclaw 就是你需要的。\n\nnpm package: [`@oyasmi/pipiclaw`](https://www.npmjs.com/package/@oyasmi/pipiclaw)\n\n文档入口：\n\n- 配置手册：[docs/configuration.md](./docs/configuration.md)\n- 事件与子代理使用指南：[docs/events-and-sub-agents.md](./docs/events-and-sub-agents.md)\n- 部署与运维指南：[docs/deployment-and-operations.md](./docs/deployment-and-operations.md)\n- 安全文档：[docs/security.md](./docs/security.md)\n\n## 功能特性（Features）\n\n- 原生支持钉钉 Stream Mode，不需要消息中转服务，不需要公网IP\n- 支持 AI Card 过程展示，思考、工具执行和状态更新可以持续流式呈现\n- 支持 `/help`、`/new`、`/compact`、`/session`、`/model`\n- 忙碌时可继续接收 `/steer`、`/followup`、`/stop`\n- 按工作区 / 会话通道（workspace / channel）分层管理 `SOUL.md`、`AGENTS.md`、`SESSION.md`、`MEMORY.md`、`HISTORY.md`\n- 支持预定义子代理（sub-agent）和临时内联子代理（inline sub-agent）\n- 支持立即、单次、周期三类事件调度\n- 支持自定义模型提供方（provider）和模型（model）配置\n- 内建 `web_search` / `web_fetch`，支持联网搜索与网页抓取\n- 内置工具层安全防护：`bash` 命令守卫、文件路径守卫、敏感路径拒绝、阻断审计日志\n\n## 安全说明（Security）\n\nPipiclaw 当前已经内置一轮工具层安全增强：\n\n- `bash` 会拦截明显高风险命令\n- `read` / `write` / `edit` / `attach` 会做统一路径检查\n- 默认允许访问用户主目录中的普通工作文件，但会拒绝常见凭据、私钥、浏览器资料、系统敏感文件等位置\n- 可通过 `~/.pi/pipiclaw/security.json` 做实例级策略调整\n\n如果你要了解默认策略、已知边界、推荐模板和完整配置示例，请直接看：\n\n- [docs/security.md](./docs/security.md)\n\n## 快速开始（Quickstart）\n\n从零开始，让 Pipiclaw 在你的钉钉里成功回复第一条消息。可以直接让Agent帮你完成。如果你希望自己逐步操作，再看后面的“自己动手安装”。\n\n### 给 AI Agent 的安装说明（For AI Agent）\n\n可以让 AI Agent 直接帮你完成安装、初始化、配置和启动，把下面整段文字复制给你常用的 AI Agent （如 Claude Code、Codex、OpenCode 等）：\n\n```text\n请帮我在这台机器上安装并初始化 Pipiclaw，并尽量把它配置到“可以开始使用”的状态。按下面要求执行：\n\n1. 先检查 Node.js 是否可用，版本必须 \u003e= 22。\n   - 如果未安装，或版本低于 22，不要继续安装 Pipiclaw，直接告诉我需要先安装或切换到 Node.js 22+。\n\n2. 安装 Pipiclaw：\n   - 优先执行：npm install -g @oyasmi/pipiclaw\n   - 如果全局安装因为权限失败，不要默认使用 sudo。\n   - 先把报错告诉我，再询问我希望怎么处理。\n\n3. 安装完成后，执行一次 pipiclaw，让它初始化默认目录：\n   - ~/.pi/pipiclaw/\n   - ~/.pi/pipiclaw/workspace/\n\n4. 继续帮我完成基础配置，但先逐项询问我是否愿意现在提供这些信息：\n   - 钉钉应用的 clientId\n   - 钉钉应用的 clientSecret\n   - AI Card 的 cardTemplateId\n   - 模型接入方式：Anthropic，或自定义 provider\n\n5. 关于钉钉配置：\n   - AI Card 是推荐配置，不是可有可无的装饰。正常使用时建议配上。\n   - 如果我愿意提供 clientId、clientSecret、cardTemplateId，就直接帮我写入 ~/.pi/pipiclaw/channel.json\n   - robotCode 可以先留空\n   - allowFrom 可以先设为 []\n   - 如果我暂时不提供 cardTemplateId，也可以先留空，但最后要明确提醒我后续补上\n   - 不要把 any your-* placeholder 保留在最终文件里\n\n6. 关于模型配置：\n   - 先问我使用哪种方式：\n     - Anthropic 默认模型\n     - 自定义 provider\n   - 如果我选择 Anthropic，再询问我是否愿意现在提供 ANTHROPIC_API_KEY\n     - 如果我提供，就按我当前环境和你的能力，帮我配置到可用\n     - 如果我不提供，就不要编造值；保留默认空 models.json，并在最后告诉我需要自己补 ~/.pi/pipiclaw/auth.json 或环境变量\n   - 如果我选择自定义 provider，至少询问这些信息：\n     - provider 名称\n     - baseUrl\n     - api 类型\n     - apiKey\n     - 至少一个 model id\n   - 如果我提供了这些值，就帮我写好 ~/.pi/pipiclaw/models.json\n   - 如果我不提供，就不要编造值；最后明确告诉我需要自己补 ~/.pi/pipiclaw/models.json\n   - 如果服务是 OpenAI-compatible，优先使用 openai-completions，并默认加上 compat：\n     - supportsDeveloperRole: false\n     - supportsReasoningEffort: false\n\n7. 配置完成后，分两种情况处理：\n   - 如果还缺关键配置，就不要假装已经可用：\n     - 明确列出还缺什么\n     - 明确指出应该修改哪个文件\n     - 提醒我补完后再运行 pipiclaw\n   - 如果关键参数已经齐全，不要只告诉我如何启动；先询问我是否需要你现在直接帮我启动 Pipiclaw\n     - 如果我同意，你就直接启动 pipiclaw\n     - 启动后要检查输出，告诉我是启动成功，还是遇到了问题\n     - 如果遇到问题，要把问题类型、关键信息和下一步解决建议说清楚\n     - 如果启动成功，要提醒我去钉钉里先发送 /model 验证模型是否可见，再发送一条普通消息做首次验证\n     - 如果我不同意立即启动，就告诉我后续该如何手动启动\n\n8. 如果我选择“先安装，稍后自己改配置”，你就完成安装和初始化即可，但最后必须明确告诉我下一步至少要改这些文件中的哪些：\n   - ~/.pi/pipiclaw/channel.json\n   - ~/.pi/pipiclaw/auth.json\n   - ~/.pi/pipiclaw/models.json\n   - ~/.pi/pipiclaw/settings.json（如果需要固定默认模型）\n\n9. 整个过程中不要假装已经成功。\n   - 做过的操作和写过的文件要明确告诉我\n   - 如果某一步无法继续，要直接说明卡在哪里\n```\n\n### 自己动手安装（For Human）\n\n如果你希望自己逐步完成安装和配置，可以按下面步骤操作。\n\n#### 1. 环境要求（Requirements）\n\n- Node.js `\u003e= 22`\n- 一个可用的钉钉企业内部应用\n- 至少一种可用的模型接入方式\n  - 直接使用 Anthropic 默认模型\n  - 或在 `models.json` 中配置自定义模型提供方（provider）\n\nWindows 补充说明：\n\n- Pipiclaw 的工具执行层默认按 POSIX shell 语义工作\n- 推荐在 Windows 上使用 WSL2 安装和运行 Pipiclaw\n- 不推荐直接在 Windows host 模式下配合 Git Bash 使用；这种方式在工具调用中更容易遇到兼容性问题，尤其是 skills 依赖的外部工具\n- 仅在无法使用 WSL2 时，再考虑安装 Git Bash，并确保 `bash` 可在 PATH 中找到\n- 如果 Windows host 模式下 `bash` 不在 PATH 中，可以设置 `PIPICLAW_SHELL` 指向具体可执行文件，例如 `C:\\Program Files\\Git\\bin\\bash.exe`\n- 如果你不想依赖本机 shell 环境，推荐直接使用 Docker sandbox\n\n#### 2. 安装（Install）\n\n```bash\nnpm install -g @oyasmi/pipiclaw\n```\n\n#### 3. 初始化（Initialize）\n\n第一次运行会自动初始化配置目录：\n\n```bash\npipiclaw\n```\n\n程序会创建：\n\n```text\n~/.pi/pipiclaw/\n├── channel.json\n├── auth.json\n├── models.json\n├── settings.json\n├── tools.json\n└── workspace/\n    ├── SOUL.md\n    ├── AGENTS.md\n    ├── MEMORY.md\n    ├── ENVIRONMENT.md\n    ├── events/\n    ├── skills/\n    └── sub-agents/\n```\n\n默认 app home 是 `~/.pi/pipiclaw/`。如果你希望把 Pipiclaw 的所有配置和运行文件放到别处，可以在启动前设置：\n\n```bash\nexport PIPICLAW_HOME=/your/custom/pipiclaw-home\n```\n\n设置后，`channel.json`、`auth.json`、`models.json`、`settings.json`、`tools.json` 和整个 `workspace/` 都会改为从这个目录读取和写入。\n\n如果你无法使用 WSL2，选择在 Windows host 模式下配合 Git Bash 运行，并且 `bash` 不在 PATH 中，也可以一并设置：\n\n```powershell\n$env:PIPICLAW_SHELL = \"C:\\Program Files\\Git\\bin\\bash.exe\"\n```\n\n如果 `channel.json` 仍然是初始化模板，程序会提示你补全配置后再启动。这是正常行为。\n\n#### 4. 创建钉钉应用（Create a DingTalk App）\n\n在 [钉钉开放平台](https://open-dev.dingtalk.com/) 创建企业内部应用，并完成下面几项：\n\n1. 创建应用，获取 `Client ID` 和 `Client Secret`\n2. 开启机器人能力\n3. 启用 Stream Mode\n4. 建议一并创建 AI Card 模板并获取 `Card Template ID`\n\n#### 5. 填写 `channel.json`（Fill `channel.json`）\n\n编辑 `~/.pi/pipiclaw/channel.json`：\n\n```json\n{\n  \"clientId\": \"your-dingtalk-client-id\",\n  \"clientSecret\": \"your-dingtalk-client-secret\",\n  \"robotCode\": \"\",\n  \"cardTemplateId\": \"\",\n  \"cardTemplateKey\": \"content\",\n  \"allowFrom\": []\n}\n```\n\n为了让第一轮接入更稳，上面的示例先把 `cardTemplateId` 留空；如果你已经准备好 AI Card 模板，推荐直接填入真实值。\n\n最少只需要：\n\n- `clientId`\n- `clientSecret`\n\n常见可选项：\n\n- `robotCode`\n  留空时会回退到 `clientId`\n- `cardTemplateId`\n  建议配置；留空时表示暂不启用 AI Card\n- `allowFrom`\n  设为 `[]` 或删除时表示允许所有人\n\n推荐把 AI Card 一起配上，这样在钉钉里能直接看到过程更新。只有在排查接入链路时，才建议临时把 `cardTemplateId` 留空。\n\n#### 6. 配置模型（Configure Models）\n\nPipiclaw 启动后要想真正生成回复，还需要有可用模型。这里通常有两种接入方式。\n\n#### 方案 A：使用内置 Anthropic 默认模型（Option A: Use the Built-in Anthropic Default）\n\n如果你直接使用 Anthropic，`models.json` 可以保持默认内容：\n\n```json\n{\n  \"providers\": {}\n}\n```\n\n然后提供 Anthropic 凭据即可。最简单的是环境变量：\n\n```bash\nexport ANTHROPIC_API_KEY=sk-ant-...\n```\n\n也可以写到 `~/.pi/pipiclaw/auth.json`：\n\n```json\n{\n  \"anthropic\": {\n    \"type\": \"api_key\",\n    \"key\": \"sk-ant-...\"\n  }\n}\n```\n\n#### 方案 B：添加自定义模型提供方（Option B: Add a Custom Provider）\n\n如果你使用的是 OpenAI-compatible 网关、代理、自建服务或聚合平台，可以在 `~/.pi/pipiclaw/models.json` 里添加一个自定义模型提供方（provider）。\n\n一个可以直接改名替换后使用的最小示例：\n\n```json\n{\n  \"providers\": {\n    \"my-gateway\": {\n      \"baseUrl\": \"https://llm.example.com/v1\",\n      \"api\": \"openai-completions\",\n      \"apiKey\": \"your-api-key\",\n      \"compat\": {\n        \"supportsDeveloperRole\": false,\n        \"supportsReasoningEffort\": false\n      },\n      \"models\": [\n        {\n          \"id\": \"gpt-4.1\"\n        }\n      ]\n    }\n  }\n}\n```\n\n这个例子里最关键的四项是：\n\n- `baseUrl`\n- `api`\n- `apiKey`\n- `models`\n\n说明：\n\n- `apiKey` 可以直接写真实 key\n- 也可以写环境变量名，或 `!command`\n- 很多 OpenAI-compatible 服务不支持 `developer` role / `reasoning_effort`\n  如果遇到请求兼容性问题，先保留上面的 `compat`\n\n如果你不想把凭据直接写进 `models.json`，也可以改成同名模型提供方（provider）的 `auth.json` 配置，例如：\n\n```json\n{\n  \"my-gateway\": {\n    \"type\": \"api_key\",\n    \"key\": \"your-api-key\"\n  }\n}\n```\n\n同时把 `models.json` 中的 `apiKey` 改成同一个值，或者改成环境变量名。完整配置手册见 [docs/configuration.md](./docs/configuration.md)。\n\n#### 7. 可选：设置默认模型（Optional: Set a Default Model）\n\n如果你希望固定默认模型，可以编辑 `~/.pi/pipiclaw/settings.json`：\n\n```json\n{\n  \"defaultProvider\": \"my-gateway\",\n  \"defaultModel\": \"gpt-4.1\"\n}\n```\n\n如果不设置，Pipiclaw 会使用当前可用模型列表里的第一个。\n\n#### 8. 启动 Pipiclaw（Start Pipiclaw）\n\n```bash\npipiclaw\n```\n\n#### 9. 可选：配置内建 Web 工具（Optional: Configure Built-in Web Tools）\n\n如果你希望助手直接使用 `web_search` / `web_fetch`，可以编辑 `~/.pi/pipiclaw/tools.json`。\n\n第一次启动时，Pipiclaw 会自动生成一份默认关闭的 `tools.json` 模板。它已经带了 Brave 的示例配置，以及可选代理示例，方便你直接改成可用状态：\n\n```json\n{\n  \"tools\": {\n    \"web\": {\n      \"enable\": false,\n      \"proxy\": null,\n      \"search\": {\n        \"provider\": \"brave\",\n        \"apiKey\": \"\"\n      }\n    }\n  },\n  \"_examples\": {\n    \"proxy\": \"http://127.0.0.1:7890\",\n    \"apiKey\": \"BSA...\"\n  }\n}\n```\n\n最常见的启用方式是：\n\n1. 把 `tools.web.enable` 改成 `true`\n2. 把 `tools.web.search.apiKey` 改成你自己的 Brave key\n3. 如果需要代理，再把 `_examples.proxy` 的值抄到 `tools.web.proxy`\n\n未设置 `tools.web.proxy` 时，web 工具会回退到标准环境变量：`HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY`、`NO_PROXY`。DingTalk runtime 也会尊重同一套环境变量。\n\n#### 10. 在钉钉中验证（Verify in DingTalk）\n\n建议先给机器人发送：\n\n```text\n/model\n```\n\n确认当前可见模型和默认模型都符合预期后，再发送一条普通消息，例如：\n\n- `/model` 会列出当前模型和可用模型\n- 切换时支持精确的 `provider/modelId`、精确的 `modelId`，以及能唯一命中的片段字符串，例如 `/model turbo`\n\n```text\n请介绍一下你自己，并说明你现在能做什么\n```\n\n如果一切正常：\n\n- 如果已经配置 AI Card，你会在钉钉里看到过程更新；这也是推荐的使用方式\n- 如果暂时没有配置 AI Card，机器人会直接发送普通消息\n- Pipiclaw 会在本地创建对应的会话通道目录\n- 后续会话会复用该会话通道的工作区（workspace）与记忆文件\n\n## 配置（Configuration）\n\n配置与使用相关的文档建议按下面顺序阅读：\n\n| 文档 | 适合什么场景 |\n|------|--------------|\n| [docs/configuration.md](./docs/configuration.md) | 查配置项、字段含义、模型与钉钉配置 |\n| [docs/events-and-sub-agents.md](./docs/events-and-sub-agents.md) | 配置并使用定时事件、预定义子代理 |\n| [docs/deployment-and-operations.md](./docs/deployment-and-operations.md) | 长期运行、升级、日志、备份与排障 |\n\n### 配置文件（Config Files）\n\n默认根目录是 `~/.pi/pipiclaw/`；如果设置了 `PIPICLAW_HOME`，下面这些路径都会切换到该目录下。\n\n| 文件 | 用途 |\n|------|------|\n| `~/.pi/pipiclaw/channel.json` | 钉钉应用配置 |\n| `~/.pi/pipiclaw/auth.json` | 模型认证信息 |\n| `~/.pi/pipiclaw/models.json` | 自定义模型提供方 / 模型，或覆盖内置模型提供方 |\n| `~/.pi/pipiclaw/settings.json` | 默认模型提供方 / 模型和运行时设置 |\n| `~/.pi/pipiclaw/tools.json` | 内建工具配置，例如 `tools.web` |\n\n### 环境变量（Environment Variables）\n\n| 变量 | 用途 |\n|----------|------|\n| `ANTHROPIC_API_KEY` | Anthropic API Key |\n| `PIPICLAW_HOME` | 覆盖默认的 `~/.pi/pipiclaw/` 根目录 |\n| `PIPICLAW_DEBUG` | 调试模式，会把上下文写到 `last_prompt.json` |\n| `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` / `NO_PROXY` | 标准代理环境变量；DingTalk runtime 和 web 工具都会尊重它们 |\n\n## 命令（Commands）\n\nPipiclaw 有两层命令。\n\n### 传输层命令（Transport Commands）\n\n这些命令由钉钉运行时（DingTalk runtime）直接处理：\n\n| 命令 | 说明 |\n|------|------|\n| `/help` | 查看内置命令帮助 |\n| `/stop` | 停止当前正在执行的任务 |\n| `/steer \u003cmessage\u003e` | 在当前任务继续执行时追加新的引导信息 |\n| `/followup \u003cmessage\u003e` | 把新的请求排队，等当前任务结束后再执行 |\n\n忙碌时，普通消息默认等价于 `/steer \u003cmessage\u003e`。\n\n### 会话层命令（Session Commands）\n\n这些命令由 `AgentSession` 扩展命令（extension command）立即执行，不会作为普通 prompt 发给模型：\n\n| 命令 | 说明 |\n|------|------|\n| `/new` | 开启一个新的会话 |\n| `/compact [instructions]` | 手动压缩当前会话上下文，可附带额外说明 |\n| `/session` | 查看当前会话状态、消息统计、token 使用量和当前模型 |\n| `/model [provider/modelId|modelId|substring]` | 查看当前模型，或切换到指定模型 |\n\n`/model` 的匹配顺序是：\n\n1. 精确匹配 `provider/modelId`\n2. 精确匹配 `modelId`\n3. 对完整的 `provider/modelId` 做子字符串匹配\n\n只有当片段字符串能唯一命中一个可用模型时才会切换。例如：\n\n- `/model qwen`\n- `/model k2.5`\n- `/model turbo`\n- `/model zpai`\n\n像 `/model glm5` 这种不构成子字符串的输入不会命中。\n\n## 工作区结构（Workspace Layout）\n\nPipiclaw 的核心不是一个临时机器人实例，而是一组长期存在的工作区（workspace）文件。\n\n```text\n~/.pi/pipiclaw/\n├── channel.json\n├── auth.json\n├── models.json\n├── settings.json\n└── workspace/\n    ├── SOUL.md\n    ├── AGENTS.md\n    ├── MEMORY.md\n    ├── ENVIRONMENT.md\n    ├── events/\n    ├── skills/\n    ├── sub-agents/\n    ├── dm_{userId}/\n    │   ├── SESSION.md\n    │   ├── MEMORY.md\n    │   ├── HISTORY.md\n    │   ├── .channel-meta.json\n    │   ├── context.jsonl\n    │   ├── log.jsonl\n    │   └── subagent-runs.jsonl\n    └── group_{conversationId}/\n        └── ...\n```\n\n其中：\n\n- `SOUL.md`\n  定义助手身份、语气和回复风格\n- `AGENTS.md`\n  定义工作规则和行为约束\n- `SESSION.md`\n  当前工作态\n- `MEMORY.md`\n  稳定事实、决策和偏好\n- `HISTORY.md`\n  更早上下文的摘要\n\n## 记忆模型（Memory Model）\n\nPipiclaw 不会把所有历史对话无上限地塞进 prompt，而是按层管理：\n\n- `workspace/MEMORY.md`\n  工作区级稳定背景\n- `\u003cchannel\u003e/SESSION.md`\n  当前任务和短期上下文\n- `\u003cchannel\u003e/MEMORY.md`\n  会话通道级 durable facts、decisions、preferences\n- `\u003cchannel\u003e/HISTORY.md`\n  更早会话的摘要历史\n\n运行时主要做两件事：\n\n- relevant recall\n  按当前请求从 `SESSION.md` / `MEMORY.md` / `HISTORY.md` 里挑少量相关片段注入当前 prompt\n- consolidation\n  在 compaction 或 session trimming 前刷新 `SESSION.md`，并把值得保留的信息沉淀到 `MEMORY.md` / `HISTORY.md`\n\n## 事件与子代理（Events and Sub-Agents）\n\n`workspace/events/` 和 `workspace/sub-agents/` 是 Pipiclaw 非常重要的两类长期能力：\n\n- 定时事件适合做提醒、巡检、定期回顾和固定流程触发\n- 预定义子代理适合把 reviewer、researcher、planner 这类角色沉淀为可复用能力\n\n这两部分更接近“日常使用”而不是基础配置，单独整理在 [docs/events-and-sub-agents.md](./docs/events-and-sub-agents.md)。\n\n## 故障排查（Troubleshooting）\n\n### `pipiclaw` 首次启动即退出（`pipiclaw` Exits on First Run）\n\n通常是因为 `channel.json` 仍然保留了初始化占位值。\n\n优先检查这些字段：\n\n- `clientId`\n- `clientSecret`\n- `robotCode`\n- `cardTemplateId`\n- `allowFrom`\n\n第一次接通时，最省事的做法是：\n\n- 把 `robotCode` 设为空字符串\n- 把 `cardTemplateId` 设为空字符串\n- 把 `allowFrom` 设为 `[]`\n\n确认链路正常后，建议尽快把 AI Card 配上。\n\n### 机器人已启动，但第一次模型调用失败（The Bot Starts but the First Model Call Fails）\n\n优先检查：\n\n- 如果 `models.json` 为空，是否已经提供可用的 Anthropic 凭据\n- 如果使用自定义模型提供方，`models.json` 是否包含 `baseUrl`、`api`、`apiKey`、`models`\n- `auth.json` 是否使用了对象格式，而不是直接写成字符串\n- 如果是 OpenAI-compatible 服务，是否需要：\n  - `\"supportsDeveloperRole\": false`\n  - `\"supportsReasoningEffort\": false`\n- 给机器人发送 `/model`，确认当前可见模型和默认模型是否正确；如需切换，也可以用唯一命中的片段，例如 `/model turbo`\n\n### 机器人能收到消息，但没有回复（The Bot Receives Messages but Does Not Reply）\n\n优先检查：\n\n- 模型认证是否可用\n- `models.json` 是否声明了你要使用的模型提供方 / 模型\n- `allowFrom` 是否把你的账号挡住了\n- 钉钉机器人 Stream Mode 是否已开启\n- 如果配置了 `cardTemplateId`，该模板是否有效\n\n如果只是想先验证链路，可以临时把 `cardTemplateId` 留空；正常使用时仍然建议启用 AI Card。\n\n### 需要查看精确提示词（Need to Inspect the Exact Prompt）\n\n设置：\n\n```bash\nexport PIPICLAW_DEBUG=1\n```\n\n之后运行时会在对应的会话通道目录下写出 `last_prompt.json`。\n\n## 开发（Development）\n\n```bash\nnpm install\nnpm run build\nnpm run check\n```\n\n常用脚本：\n\n- `npm run typecheck`\n- `npm run test`\n- `npm run test:e2e`\n- `npm run check`\n\n端到端测试说明：\n\n- `npm run test:e2e` 会运行“除钉钉渠道外”的完整 E2E\n- 它会使用真实 runtime、真实 `ChannelStore`、真实工具/记忆/Sidecar/LLM\n- 只 mock 钉钉传输层，不连接真实钉钉 Stream\n- 运行前需要可用模型凭据：优先读取 `${PIPICLAW_HOME:-~/.pi/pipiclaw}/auth.json`，否则回退到 `ANTHROPIC_API_KEY`\n- E2E 默认不包含在 `npm run test` 中，避免日常测试被真实 LLM 依赖和调用成本影响\n\n## 许可证（License）\n\nApache License 2.0. See [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foyasmi%2Fpipiclaw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foyasmi%2Fpipiclaw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foyasmi%2Fpipiclaw/lists"}