my-pi-agent

基于 Pi Agent 搭建的 Agentic Engineering Loop 项目。

项目从个人 AI 开发助手起步，当前核心仍是本机 personal mode：记忆、任务编排、飞书通道、coding workflow、验证、运行诊断和桌面端宿主。新的演进方向是企业级 Agentic SDLC Loop：把公司 Agent、工单、MRD 或 webhook 的上游分析结果作为输入，沉淀成结构化需求包、拆分校验、测试场景和验收标准，再进入后续 sandbox 执行、验证、证据归档和回写。

分层编排架构支持自动任务分析、workflow 路由、pattern 组合和执行。通过工厂模式设计，核心组件可独立替换；企业级 loop 能力先以独立 apps/engineering-loop 入口和 packages/loop-workflows workflow 包起步，不影响现有 personal mode。

✨ 核心能力

能力	说明
自动编排	用户描述任务 → 自动分析复杂度 → 路由到 workflow → 在 workflow 内组合 patterns 执行
双层记忆	短期记忆（日常积累） + 长期记忆（每夜沉淀），跨会话持久
分层执行	Workflow: simple / dag / react / research / browser_use / swarm；Patterns(runnable): sequential / parallel / react / reflection / tot（其中 reflection / tot 只在显式开放的 workflow 边界内可选）
长任务队列	创建、暂停、恢复、重试；运行时默认使用 SQLiteTaskStore，并基于 lease/checkpoint 从异常中断恢复到安全步骤边界
运行诊断	`task_diagnose` / `run_diagnose` 可查看结构化轨迹、最近 progress、失败/警告摘要
首次 setup	`pnpm run setup` 交互式补 `.env`、模式预设、初始化 `memory/*` 并自动跑 doctor
启动前自检	`pnpm run doctor` 检查 Pi CLI、MCP bootstrap、模型/飞书/OfficeCLI 配置和运行态目录
运维审计	`setup / doctor / smoke / check` 运行结果统一写入 `memory/runs/*.json`；`pnpm run audit` 可汇总最近运行、阻塞项、恢复建议和证据
个人控制台	`pnpm run console` / `pnpm run console:web` / `pnpm run desktop` 在本机只读查看任务、任务事件流水、运行诊断、运维阻塞和数据体积
桌面端宿主	`apps/desktop` 已起步为 Electron 宿主，负责窗口、托盘、单实例锁、开机启动、自动更新入口和本机 Web 控制台服务生命周期
定时调度	每晚 00:00 记忆同步，每 5 分钟任务队列 tick
飞书通道	WebSocket 长连接，无需公网域名，无需配置加密策略
个人主人访问控制	飞书首次绑定唯一主人，非主人消息不会触发附件下载、模型或任务
实施前审批	飞书实现类 `/code` 先生成只读计划，主人确认后才允许写入和验证
飞书接口文档附件	上传 `.md/.markdown` 接口文档后，同聊天后续 `/code` 会自动作为只读对接上下文
远程 Skill 安装	飞书端支持确认式安装，可按当前 my-pi-agent 共享层或当前绑定项目的 project scope 落盘
Skill 自动发现	编排层只扫描 target project + 当前配置的 my-pi-agent 共享层（兼容 legacy fallback），把匹配候选注入子任务 prompt
高频 Workflow Skills	内置项目结构速览、Git 工作流、代码审查、技术调研、Spec/PRD 互审，优先覆盖日常 coding 工作流
统一图片生成	`image_generate` 作为共享图像能力，飞书 `/image` 可生成并回传图片
Office 生成与文件回传	默认走官方 `officecli` MCP + 本仓库共享 Office skill，支持 Word / PowerPoint / Excel 创建、改版、美化和文件回传
模型分层	Analyzer 可单独配置轻量路由模型，执行步骤继续使用当前 Pi 主模型
统一请求入口	飞书普通文本先经 request router；简单请求走 Pi direct，复杂请求走 orchestrator
Coding Agent Workflow	`coding_agent_run` 对实现类请求默认走 coordinator → workers → reviewers → verifier；低风险小任务会自动收敛为短执行面 coordinator → workers → verifier；对纯 review/盘点类请求停在 coordinator 审查结论
Deterministic Verifier	verifier 可输出 `verificationPlan`，由 runner/harness 真正执行 shell / node-state / http / mcp / browser probe
Agentic SDLC Loop 预留	`apps/engineering-loop` 作为企业级应用入口占位，`packages/loop-workflows` 先起步 `agentic-sdlc-loop`：自然语言原始需求 → 结构化需求包 → 公司 Agent 拆分需求 → 拆分结果校验 → 测试场景 / 验收标准
模块化架构	分析器、路由器、拆解器、执行器、存储层均可独立替换

🧭 文档导航

README 只保留项目定位、核心能力和上手路径；深层架构说明集中维护在 docs，避免首页和 ADR 长期漂移。

文档	内容
docs/runtime-architecture.md	monorepo 边界、编排流程、prompt 工程、coding workflow、工厂替换点
docs/desktop/README.md	桌面端开发说明、Electron 打包镜像约定和验收基线
docs/desktop/roadmap.md	Desktop 后续开发路线图
docs/spec.md	功能规格与当前版本口径
docs/decision-log.md	架构决策记录与回滚说明
docs/manual-regression-checklist.md	手动回归和真实链路检查
docs/todo.md	当前待办与后续方向

🧩 当前边界

personal mode 已可用：飞书单主人、本机任务队列、coding workflow、verifier、控制台、桌面端宿主和运行诊断。
enterprise loop 正在起步：当前只预留 engineering-loop 应用入口和 agentic-sdlc-loop workflow 阶段目录。
需求/设计 Agentic Loop 暂由公司 Agent 承担，本项目先承接其文本拆分结果，不重复实现上游需求分析。
sandbox 执行层尚未落地；后续测试、前端测试、接口测试和压测都应经过统一 sandbox execution layer。

🚀 快速开始

1. 安装

# 克隆项目
git clone <repo-url> my-pi-agent
cd my-pi-agent

# 启用 packageManager 声明的 pnpm 版本并安装依赖
corepack enable
pnpm install

# 确保 Pi Agent 已全局安装
pnpm add -g @earendil-works/pi-coding-agent

2. 配置模型

复制 .env.example 为 .env，至少配置一个 Pi 支持的 LLM provider。只跑本地文本 Agent / /code 主流程时，不强制要求 Z.ai；OpenAI、Anthropic、Google、DeepSeek、OpenRouter 等 provider 只要 Pi 当前版本能识别并拿到 key，也可以作为主执行模型：

cp .env.example .env

.env 示例：

ZAI_CODING_CN_API_KEY=xxx
# 同时用于 web-search-prime / web-reader / zread 远程 MCP 兜底鉴权
# 以及 Vision MCP（zai-vision-mcp）图片理解优先链路

# 可选：图片生成默认走 SiliconFlow 国内 API
# IMAGE_GENERATION_PROVIDER=siliconflow
# SILICONFLOW_API_KEY=xxx
# IMAGE_GENERATION_API_KEY=xxx
# IMAGE_GENERATION_ENDPOINT=https://api.siliconflow.cn/v1
# IMAGE_GENERATION_MODEL=Tongyi-MAI/Z-Image-Turbo
# IMAGE_GENERATION_SIZE=1024x1024

# 可选：图片理解默认走 SiliconFlow GLM-4.5V
# VISION_API_KEY=xxx
# VISION_ENDPOINT=https://api.siliconflow.cn/v1
# VISION_MODEL=zai-org/GLM-4.5V

# 可选：主执行模型；影响 pnpm run agent、飞书直连会话和 coding workflow 子会话
# MAIN_MODEL=glm-5.2
# MAIN_MODEL=openai/gpt-4.1
# MAIN_MODEL=anthropic/claude-sonnet-4-5
# MAIN_MODEL=google/gemini-2.5-pro

# 可选：coding workflow 角色级 thinking
# CODING_COORDINATOR_THINKING=high
# CODING_WORKER_THINKING=medium
# CODING_REVIEWER_THINKING=low
# CODING_VERIFIER_THINKING=medium

# 可选：控制面使用轻量模型做路由/补判；同一颗小模型也会被 worker worktree 的临时产物补判复用
# CONTROL_MODEL=glm-4.7

# ANTHROPIC_API_KEY=xxx
# OPENAI_API_KEY=xxx
# GITHUB_TOKEN=xxx
# MCP_RUNTIME=docker
# MCP_DOCKER_IMAGE=my-pi-agent-mcp-runtime:0.1
# MCP_DOCKER_AUTO_BUILD=1
# MCP_CHROME_MODE=docker
# MCP_CHROME_MODE=host
# MCP_CHROME_REMOTE_DEBUGGING_URL=http://host.docker.internal:9222
# MCP_NPX=/path/to/npx
# MCP_PNPM=/path/to/pnpm
# MCP_PYTHON=/path/to/python3.12
# MCP_PYPI_INDEX_URL=https://pypi.org/simple

MAIN_MODEL 支持 glm-5.2、glm5.2、zai-coding-cn/glm-5.2、zai/glm-5.2 或完整的 provider/model-id 写法。只写 glm-5.2 这类 GLM model id 时，pnpm run agent 会优先按当前 .env 里的 ZAI_CODING_CN_API_KEY 选择 zai-coding-cn，否则使用 zai；非 GLM 模型建议始终写完整 provider/model-id，例如 openai/gpt-4.1、anthropic/claude-sonnet-4-5、google/gemini-2.5-pro、openrouter/anthropic/claude-sonnet-4.5。扩展内部创建子 AgentSession 时会复用当前 Pi 主模型 provider。未配置 MAIN_MODEL 时，行为保持为 Pi 当前选择的主模型，可继续用 /model、Ctrl+L、Ctrl+P 或 pi --model ... 临时切换。

coding workflow 还支持 4 个角色级 thinking 环境变量：CODING_COORDINATOR_THINKING、CODING_WORKER_THINKING、CODING_REVIEWER_THINKING、CODING_VERIFIER_THINKING。默认分别是 high / medium / low / medium；只影响 /code / coding_agent_run 的这 4 个职责步骤，不影响普通会话的全局 thinkingLevel。如果某个值没配或写错，会回退到对应默认值。执行面是否走 short/full 仍由控制面按风险动态判断，不通过 .env 强制切换。

CONTROL_MODEL 支持 glm-4.7、zai-coding-cn/glm-4.7、zai/glm-4.7、zai:glm-4.7 或完整的 provider/model-id 写法。只写 glm-4.7 这类 model id 时，会优先复用当前 Pi 主模型所在的自定义 provider。推荐让控制面使用 glm-4.7、glm-4.5-air、glm-5-turbo 等轻量模型，让主流程执行使用 MAIN_MODEL 或 Pi 当前选择的更强模型。当它被复用于 worker worktree 的临时产物补判时，系统只会对“未跟踪且不明显是源码”的文件发起一次保守分类；没有模型或模型不给高置信度结论时，一律保留文件，不会静默吞掉真实改动。

图片生成现在先经过 IMAGE_GENERATION_PROVIDER 分派，当前内置 provider 只有 siliconflow。IMAGE_GENERATION_ENDPOINT 默认是 https://api.siliconflow.cn/v1，IMAGE_GENERATION_MODEL 默认是 Tongyi-MAI/Z-Image-Turbo，默认尺寸是 1024x1024。比例别名会映射为常用尺寸：1:1 -> 1024x1024、16:9 -> 1280x720、9:16 -> 720x1280、4:3 -> 1152x864、3:4 -> 864x1152。如果 SiliconFlow key 不可用或额度不足，Agent 会把失败原因原样反馈给飞书或 image_generate 调用方；如果配置成未实现的 provider，会在调用前返回明确的“不支持 provider”错误。桌面 Web 控制台里的自然语言图片生成请求会先走 baoyu-cover-image 规则，写入 cover-image/<topic>/prompts/，再调用同一套 image_generate provider，最终图片保存到 cover-image/<topic>/cover.png。

飞书图片理解现在按优先级逐级回退：当 ZAI_CODING_CN_API_KEY 已配置时，先走 Vision MCP（zai-vision-mcp）；如果 Vision MCP 失败，会继续尝试独立视觉链路。独立视觉链路的 VISION_ENDPOINT 默认是 https://api.siliconflow.cn/v1，VISION_MODEL 默认是 zai-org/GLM-4.5V，VISION_API_KEY 未配置时依次回退到 SILICONFLOW_VISION_API_KEY、SILICONFLOW_API_KEY。若独立视觉链路不可用，飞书仍会回退到当前 active model 的多模态能力；如果当前模型不在视觉能力白名单内，会返回可执行的配置提示。

pnpm run agent 会自动加载 .env。如果直接运行 pi，需要自己先把环境变量导出到当前 shell。

启动后在交互界面里切换模型：

操作	说明
`/model`	打开模型选择器
`Ctrl+L`	快捷键切换模型
`Ctrl+P`	在已配置的模型间轮换
`MAIN_MODEL=glm-5.2`	写入 `.env` 后，`pnpm run agent` 固定使用该主模型
`pi --model anthropic/claude-sonnet-4`	启动时指定模型

自定义 provider 配置见 ~/.pi/agent/models.json。

3. Docker 一键启动

如果只想把项目交给别人按容器方式跑，推荐走 Docker Compose。镜像会内置 Node、Pi CLI、Python、Chromium、OfficeCLI 和项目依赖；用户只需要准备 Docker、.env 里的 key，以及可选的宿主代码目录挂载。

cp .env.example .env
# 编辑 .env，至少填 FEISHU_APP_ID / FEISHU_APP_SECRET 和一个主模型 key

docker compose up --build agent

常用 .env 最小项：

FEISHU_APP_ID=xxx
FEISHU_APP_SECRET=xxx
FEISHU_OWNER_BOOTSTRAP_TOKEN=自己生成一段随机字符串

ZAI_CODING_CN_API_KEY=xxx
# 或 OPENAI_API_KEY / ANTHROPIC_API_KEY / GEMINI_API_KEY 等
MAIN_MODEL=glm-5.2

# 可选：让 /code 能看到宿主机代码仓库；容器内固定映射为 /workspace/repos
HOST_CODING_PROJECTS_ROOT=/Users/your-name/Documents/GitHub

compose 会把宿主机 ${HOST_CODING_PROJECTS_ROOT} 挂载到容器内 /workspace/repos，并把容器内 CODING_PROJECTS_ROOT 固定为 /workspace/repos。如果不配置 HOST_CODING_PROJECTS_ROOT，默认尝试挂载宿主机 ${HOME}/Documents/GitHub。

首次启用飞书个人主人绑定时，启动日志里的 doctor 可能提示 feishu-owner-access 未绑定；容器默认仍会继续启动。用目标飞书账号发送：

/agent bind <FEISHU_OWNER_BOOTSTRAP_TOKEN>

绑定完成后重启容器即可。需要让 doctor 失败时直接阻断启动，可以设置：

MY_PI_AGENT_REQUIRE_DOCTOR=1

容器内常用命令：

# 自检
docker compose run --rm agent pnpm run doctor

# 交互式 setup
docker compose run --rm agent pnpm run setup -- --preset feishu-lite

# 启动 Agent
docker compose up agent

注意：完整应用容器默认使用镜像内依赖运行 MCP，docker-compose.yml 会设置 MCP_RUNTIME=local 和 MCP_CHROME_MODE=headless，不需要再开启 MCP_RUNTIME=docker。后者只适用于本机启动 pnpm run agent 时，把 MCP server 额外交给 Docker 承载。

4. 首次 setup（推荐）

第一次在新机器或新仓库目录里使用时，建议先跑：

pnpm run setup

setup 会做四件事：

让你在 local-lite / coding-only / feishu-lite / full 四种模式里先选一个
按当前模式引导填写或保留 .env 里的关键字段；已有值默认保留，输入 - 可以清空
初始化 memory/generated-images、memory/generated-office、memory/feishu-attachments、memory/mcp-workspace-configs、memory/runs
默认自动跑一遍 doctor，并给出下一步建议命令

常用参数：

# 预选 setup 模式
pnpm run setup -- --preset feishu-lite

# 预选模型提供方
pnpm run setup -- --provider openai

# 只写配置，不跑 doctor
pnpm run setup -- --skip-doctor

如果你已经手动维护 .env，也仍然可以直接跳过 setup，继续用下面这些命令。

5. 启动

# 交互模式（日常使用，自动加载 .env）
pnpm run agent

# 或直接用 pi（需先手动导出环境变量）
pi

# 恢复上次会话
pnpm run agent:resume

# 继续上次对话
pnpm run agent:continue

启动后扩展会自动加载：记忆系统、定时调度、任务队列和 MCP 适配器。

6. 运行质量检查

项目现在有一套本地质量门禁：空白 diff 检查、TypeScript no-emit 类型检查、ESLint 和 Node 原生 test runner 回归基线。回归测试优先覆盖 request router、task queue、coding workflow 和飞书 /code 准备逻辑等关键控制面路径；测试脚本会自动注册 TS import hook，不需要额外编译。最近又补了三条更接近真实链路的 smoke：task queue -> shell -> diagnostics、inline coding workflow -> verifier runner、worker lane worktree -> diff -> merge。

pnpm run doctor 是启动前自检入口，只做本地确定性检查，不会主动连外部服务。它会检查仓库布局、Node 版本、关键依赖、Pi CLI、模型/飞书/GitHub 配置、飞书个人主人绑定、.mcp.json、npx/pnpm、Python 3.10+、OfficeCLI 和 memory/ 可写性；默认只在硬失败时退出非 0，使用 pnpm run doctor -- --strict 可以把 warning 也作为发布前阻断项。

pnpm run audit 会读取 memory/runs/*.json 里的最新运维记录，汇总最近一次 setup / doctor / smoke / check / dogfooding 的状态、当前阻塞、恢复建议、人工缺口和证据 run ID。setup、doctor、smoke:local、smoke:live、check 和手工 dogfooding 现在都写回同一套运行记录模型，避免再手工同步多份状态。需要把当前审计快照写回 dogfooding 展示层时，运行 pnpm run audit -- --sync-docs。

pnpm run data -- status 会展示本地数据体积和默认保留期。pnpm run data -- backup 创建核心状态快照，其中 tasks.db 通过 SQLite VACUUM INTO 生成一致性副本；记忆、任务状态、飞书主人策略、聊天上下文和技能记录只会备份，绝不自动删除。pnpm run data -- prune 默认只预览过期的运行诊断、MCP 临时配置、飞书附件缓存、历史图片/Office 产物、已移除 skill 留档和旧备份，需加 --apply 才会删除。日常维护使用：

pnpm run data -- maintain --apply

默认保留期为：MCP 临时配置 7 天，本地备份 14 天，其余可治理历史数据 30 天。可使用 --retention-days <n> 临时覆盖本次操作的全部保留期。outputs/ 属于用户交付物，不在自动清理范围内。

pnpm run console 是个人使用的本机只读 CLI 控制台：默认同时汇总任务状态、任务事件与运行诊断流水、运维阻塞/建议和可治理数据体积。它只用 SQLite 只读连接查询 memory/tasks.db，不会创建任务、写入诊断或执行清理。需要展开某项时：

# 查看任务和步骤进度
pnpm run console -- tasks
pnpm run console -- task <taskId>

# 查看任务事件与运行诊断流水，或展开一次运行详情
pnpm run console -- activity --limit 20
pnpm run console -- runs
pnpm run console -- run <runId>

pnpm run console:web 是同一事实源上的本机只读 Web 控制台。前端位于 apps/web-console，采用 React + Zustand + shadcn/ui 风格，启动前会先构建静态资源，再由本机服务托管。当前界面按 Codex 式会话工作台组织：左侧是按时间分组的会话 timeline，右侧是当前会话的消息 / 过程详情，底部输入框暂不接写入链路。它默认只监听 127.0.0.1:4318，不接受 --host、--dir 或公网监听参数，不创建任务、不执行清理、不连接飞书或 AgentSession：

# 默认监听 127.0.0.1:4318
pnpm run console:web

# 启动后自动打开浏览器
pnpm run console:web -- --open

# 端口冲突时换端口
pnpm run console:web -- --port 4319 --open

pnpm run desktop 会先构建 React Web 控制台，再由 Electron 托管同一个 127.0.0.1 控制台服务，包含窗口管理、托盘常驻、单实例锁、开机启动、崩溃恢复、打包签名和自动更新入口。日常使用桌面端时不需要再单独开终端运行 pnpm run console:web：

pnpm run desktop

可选配置：

MY_PI_AGENT_DESKTOP_BASE_DIR / MY_PI_AGENT_HOME：控制台会话、设置和运行记录的数据目录；默认当前工作目录；不影响执行工作区。
MY_PI_AGENT_DESKTOP_WORKSPACE_DIR：Agent 执行、MCP 配置和产物生成的工作区；开发态默认仓库根目录，打包态无显式配置时使用进程工作目录。
MY_PI_AGENT_WRITE_FULL_TIMEOUT_MS：桌面 full 写入任务的执行预算，默认 360000（6 分钟），最低 60 秒。
MY_PI_AGENT_DESKTOP_PORT：本机服务起始端口，默认 4318。
MY_PI_AGENT_DESKTOP_OPEN_AT_LOGIN=true：启动时登记开机启动；也可在托盘菜单切换。
MY_PI_AGENT_DESKTOP_UPDATE_URL：electron-updater generic feed 地址，用于自动更新检查。

打包入口：

pnpm run desktop:pack
pnpm run desktop:dist

macOS 签名沿用 electron-builder 标准环境变量（如 CSC_LINK / CSC_KEY_PASSWORD 或本机 Keychain identity），配置已启用 hardened runtime 与 entitlements。

pnpm run smoke:local 是稳定性 smoke 包：先跑 doctor，再集中跑飞书 /code 准备、聊天上下文、连接控制、文件/图片补发、MCP 配置派生、Office prompt、task queue E2E、inline coding workflow 和 worktree lane E2E 等相关回归。它仍然是本地确定性检查，不会替代真实飞书长连接和外部 MCP 的手动 smoke。

pnpm run smoke:live 会触碰真实本地服务：先跑 doctor，再逐个启动 filesystem / git / fetch / officecli MCP stdio server，执行 initialize + tools/list，最后用 OfficeCLI 真实创建并校验 .docx / .xlsx / .pptx 小文件后清理。Chrome DevTools MCP 默认不跑，需要时用 pnpm run smoke:live -- --include-chrome 显式加入。

高频 dogfooding 的实际结果记录在 docs/dogfooding-log.md。这份记录只写已经跑过的链路，并明确区分自动 smoke、真实本地服务 smoke 和仍需人工确认的飞书真群聊路径，避免把“脚本通过”误读成“所有真实入口都已覆盖”。

pnpm run dogfooding -- --title ... --status ... --summary ... 可以把一条真实手工 smoke 结果同时写入 memory/runs/*.json 和 docs/dogfooding-log.md，减少“结构化运行记录”和“人工日志”双写维护。

# 启动前/提测前检查本机运行环境
pnpm run doctor

# 发布前严格检查：warning 也会返回非 0
pnpm run doctor -- --strict

# 查看最近运维记录、阻塞项和恢复建议
pnpm run audit

# 生成/刷新 docs/dogfooding-log.md 里的自动审计快照
pnpm run audit -- --sync-docs

# 跑稳定性 smoke 包
pnpm run smoke:local

# 跑真实本地服务 smoke（MCP stdio + OfficeCLI）
pnpm run smoke:live

# 记录一条手工 dogfooding 结果，并自动追加到 docs/dogfooding-log.md
pnpm run dogfooding -- --title "飞书真群聊 /code" --status done --summary "真实群聊 /code 基线通过"

# 提交前推荐跑完整质量门禁
pnpm run check

# 只跑类型检查
pnpm run typecheck

# 只跑 lint（当前历史 any / unused 先保留为 warning）
pnpm run lint

# 跑完整回归
pnpm test

# 同上，保留显式命名
pnpm run test:regression

# 只跑某一类回归（按文件名子串过滤）
node ./scripts/run-regression-tests.mjs coding-workflow-preparation

提测前建议至少执行一次 pnpm run doctor 和 pnpm run check；涉及飞书通道、任务队列生命周期、Office 文件回传或外部 MCP bootstrap 的改动，先跑 pnpm run smoke:local。如果本机具备真实 MCP/Office 环境，再跑 pnpm run smoke:live，最后按 docs/manual-regression-checklist.md 补真实飞书手动 smoke，并用 pnpm run dogfooding -- ... 把结论同时写回运行记录和 dogfooding log。GitHub Actions 会在 push / PR 时跑同一套本地门禁，不读取飞书、MCP 或模型凭据。

7. 配置外部 MCP（可选）

项目通过 pi-mcp-adapter 接入外部 MCP server。项目级 .pi/settings.json 已声明所需 package；myPiAgent.sharedSkillStorage 也放在这里控制 user scope 的共享 skill 层：

{
  "packages": ["npm:[email protected]"],
  "myPiAgent": {
    "sharedSkillStorage": "project"
  }
}

sharedSkillStorage 默认是 project，表示 user scope 写入当前 my-pi-agent/.pi/user-skills/；切到 machine 后会改写到 ~/.my-pi-agent/user-skills/。

首次在本项目启动 Pi 时，信任项目后会自动安装缺失的 project package。若需要手动安装：

pi install -l npm:[email protected]

根目录 .mcp.json 已默认接入 10 个 server：常用直出工具面 filesystem / git / fetch / officecli / github / chrome-devtools，以及兜底 web-search-prime / web-reader / zread / zai-vision-mcp（默认走 MCP 代理调用）：

{
  "settings": {
    "toolPrefix": "server",
    "idleTimeout": 10,
    "directTools": false
  },
  "mcpServers": {
    "filesystem": {
      "command": "/bin/sh",
      "args": ["-c", "repo=${MY_PI_AGENT_MCP_REPO_DIR:-$(pwd)}; case \"$repo\" in /*) ;; *) repo=$(cd \"$repo\" && pwd) || exit 1;; esac; cd \"$repo\" || exit 1; script=$0; case \"$script\" in /*) exec \"$script\" \"$@\";; *) exec \"$repo/$script\" \"$@\";; esac", "./scripts/mcp-node-server.sh", "@modelcontextprotocol/server-filesystem", "."],
      "lifecycle": "lazy",
      "idleTimeout": 10,
      "directTools": true
    },
    "git": {
      "command": "/bin/sh",
      "args": ["-c", "repo=${MY_PI_AGENT_MCP_REPO_DIR:-$(pwd)}; case \"$repo\" in /*) ;; *) repo=$(cd \"$repo\" && pwd) || exit 1;; esac; cd \"$repo\" || exit 1; script=$0; case \"$script\" in /*) exec \"$script\" \"$@\";; *) exec \"$repo/$script\" \"$@\";; esac", "./scripts/mcp-python-server.sh", "mcp-server-git", "mcp_server_git", "--repository", "."],
      "lifecycle": "lazy",
      "idleTimeout": 10,
      "directTools": true
    },
    "fetch": {
      "command": "/bin/sh",
      "args": ["-c", "repo=${MY_PI_AGENT_MCP_REPO_DIR:-$(pwd)}; case \"$repo\" in /*) ;; *) repo=$(cd \"$repo\" && pwd) || exit 1;; esac; cd \"$repo\" || exit 1; script=$0; case \"$script\" in /*) exec \"$script\" \"$@\";; *) exec \"$repo/$script\" \"$@\";; esac", "./scripts/mcp-python-server.sh", "mcp-server-fetch", "mcp_server_fetch"],
      "lifecycle": "lazy",
      "idleTimeout": 10,
      "directTools": true
    },
    "officecli": {
      "command": "/bin/sh",
      "args": ["-c", "repo=${MY_PI_AGENT_MCP_REPO_DIR:-$(pwd)}; case \"$repo\" in /*) ;; *) repo=$(cd \"$repo\" && pwd) || exit 1;; esac; cd \"$repo\" || exit 1; script=$0; case \"$script\" in /*) exec \"$script\" \"$@\";; *) exec \"$repo/$script\" \"$@\";; esac", "./scripts/officecli-mcp-server.sh"],
      "lifecycle": "lazy",
      "idleTimeout": 600,
      "directTools": true,
      "env": {
        "MY_PI_AGENT_OFFICECLI_MCP_DEBUG": "1"
      }
    },
    "github": {
      "url": "https://api.githubcopilot.com/mcp/readonly",
      "auth": "bearer",
      "bearerTokenEnv": "GITHUB_TOKEN",
      "headers": {
        "X-MCP-Toolsets": "repos,pull_requests,issues"
      },
      "lifecycle": "lazy",
      "idleTimeout": 10,
      "directTools": true
    },
    "web-search-prime": {
      "url": "https://api.z.ai/api/mcp/web_search_prime/mcp",
      "auth": "bearer",
      "bearerTokenEnv": "ZAI_CODING_CN_API_KEY",
      "lifecycle": "lazy",
      "idleTimeout": 10,
      "directTools": false
    },
    "web-reader": {
      "url": "https://api.z.ai/api/mcp/web_reader/mcp",
      "auth": "bearer",
      "bearerTokenEnv": "ZAI_CODING_CN_API_KEY",
      "lifecycle": "lazy",
      "idleTimeout": 10,
      "directTools": false
    },
    "zread": {
      "url": "https://api.z.ai/api/mcp/zread/mcp",
      "auth": "bearer",
      "bearerTokenEnv": "ZAI_CODING_CN_API_KEY",
      "lifecycle": "lazy",
      "idleTimeout": 10,
      "directTools": false
    },
    "zai-vision-mcp": {
      "command": "/bin/sh",
      "args": ["-c", "repo=${MY_PI_AGENT_MCP_REPO_DIR:-$(pwd)}; case \"$repo\" in /*) ;; *) repo=$(cd \"$repo\" && pwd) || exit 1;; esac; cd \"$repo\" || exit 1; script=$0; case \"$script\" in /*) exec \"$script\" \"$@\";; *) exec \"$repo/$script\" \"$@\";; esac", "./scripts/zai-vision-mcp-server.sh"],
      "lifecycle": "lazy",
      "idleTimeout": 10,
      "directTools": false
    },
    "chrome-devtools": {
      "command": "/bin/sh",
      "args": ["-c", "repo=${MY_PI_AGENT_MCP_REPO_DIR:-$(pwd)}; case \"$repo\" in /*) ;; *) repo=$(cd \"$repo\" && pwd) || exit 1;; esac; cd \"$repo\" || exit 1; script=$0; case \"$script\" in /*) exec \"$script\" \"$@\";; *) exec \"$repo/$script\" \"$@\";; esac", "./scripts/mcp-node-server.sh", "chrome-devtools-mcp@latest"],
      "lifecycle": "lazy",
      "idleTimeout": 10,
      "directTools": true
    }
  }
}

默认情况下，这些 server 的工具会直接出现在工具列表中，例如：

filesystem_read_text_file
git_status
fetch
officecli_officecli
chrome_devtools_new_page

几个默认约束：

顶层 Pi 会话里的 filesystem / git 默认绑定当前 my-pi-agent 仓库；/code 或普通编排子 AgentSession 会派生一份临时 MCP 配置到 memory/mcp-workspace-configs/，把这些相对工作目录改绑到本次目标项目或 lane worktree。
filesystem 只放开当前执行目录，避免把整台机器的文件系统直接暴露给 agent。
filesystem 默认通过 scripts/mcp-node-server.sh 查找全局 npx，找不到时再回退到全局 pnpm dlx；如果你的 Node 不在常见 PATH 上，可以在 .env 里显式设置 MCP_NPX 或 MCP_PNPM。
chrome-devtools 默认保留本机模式；设置 MCP_RUNTIME=docker 后，默认 MCP_CHROME_MODE=docker，由容器内 chrome-devtools-mcp 启动 headless Chromium。需要复用宿主机已登录的 Chrome 时，先用 remote debugging 启动宿主 Chrome（macOS 示例：open -na "Google Chrome" --args --remote-debugging-port=9222 --user-data-dir=/tmp/my-pi-agent-chrome-debug），再设置 MCP_CHROME_MODE=host，默认连接 http://host.docker.internal:9222，也可用 MCP_CHROME_REMOTE_DEBUGGING_URL 覆盖。
git 只绑定当前仓库；fetch 和 git 共用 scripts/mcp-python-server.sh，首次调用时会自动在 memory/.mcp-python/ 下创建虚拟环境并安装官方 Python server；其中 fetch 会额外补装 socksio，兼容本机带 SOCKS 代理变量的网络环境。
如果不希望用户本机安装 npx/pnpm/Python/OfficeCLI，可以在 .env 设置 MCP_RUNTIME=docker。此模式会让 filesystem / git / fetch / officecli / chrome-devtools 走 scripts/mcp-docker-runner.sh，首次调用时自动用 docker/mcp-runtime.Dockerfile 构建 MCP_DOCKER_IMAGE（默认 my-pi-agent-mcp-runtime:0.1），并把当前目标 workspace 挂载进容器。该模式仍要求本机有 Docker；GitHub、模型、飞书、Z.ai 等凭据继续通过环境变量传入容器，不会被镜像内置。
officecli 现在走官方 OfficeCLI binary 的 officecli mcp，不是仓库里自写的 Markdown 生成器。默认直出 officecli_officecli 工具；加载官方 pptx / pitch-deck / morph-ppt / word / excel 等 skill 也通过这个工具执行 command=load_skill，后续创建、检查、改版、美化或导出继续用同一个工具。仓库内的 .pi/user-skills/officecli-document-workflow/ 会把普通 Office 请求自动导向这条链路。本机模式首次安装可执行 curl -fsSL https://d.officecli.ai/install.sh | bash；如果 binary 不在常见 PATH 上，可在 .env 里设置 OFFICECLI_BIN=/path/to/officecli。Docker 模式使用镜像内 OfficeCLI，不要求用户本机安装。
officecli.idleTimeout 默认设为 600 秒，避免长时间调研后进入生成阶段时 OfficeCLI MCP 被过早回收；如果 MCP 仍不可用，Agent 必须报告 blocked，不能用 bash 直接调用本机 officecli CLI 作为成功兜底。
github 使用 GitHub 官方 remote MCP server，默认走只读模式，并把 toolset 收敛到 repos / pull_requests / issues，尽量贴近 coding agent 的常见上下文读取场景。
web-search-prime / web-reader / zread / zai-vision-mcp 是远程或按需拉起的兜底工具面，默认 directTools=false，通过 mcp({ search: ... }) / mcp({ tool, args }) 按需调用，避免把外部搜索类工具无差别注入每个子会话上下文。
当 ZAI_CODING_CN_API_KEY 已配置时，prompt 会启用“联网检索硬规则”：凡是涉及公开信息检索、网页正文阅读、外部 GitHub 仓库资料读取，必须优先走上述 3 个 MCP，不能只靠模型记忆直接给结论。
当 ZAI_CODING_CN_API_KEY 已配置时，飞书图片识别链路会优先走 Vision MCP（zai-vision-mcp）；未配置该 key 时，继续走原有 VISION_* / SILICONFLOW_* 视觉链路与主模型 fallback。
GITHUB_TOKEN 会同时服务 GitHub MCP 和 skill-installer；ZAI_CODING_CN_API_KEY 会用于上述 z.ai 远程兜底 MCP 鉴权；如果本机默认 python3 低于 3.10，可以在 .env 里额外设置 MCP_PYTHON=/path/to/python3.10+。
pi-mcp-adapter 的 direct tools 依赖 metadata cache；新 server 第一次接进来时，如果当前会话里还没看到完整直出工具，先执行一次 /mcp reconnect <server> 或触发一次代理调用，后续会话就会稳定直出。

Deep Research 不承诺所有用户环境都有同样搜索质量。扩展会把它作为“可插拔研究工作流编排器”处理，并通过 deep_research_capability 工具和 pnpm run doctor 暴露当前能力等级：

等级	典型配置	交付边界
`B / Basic`	用户自带 MCP	能跑完整研究流程，但搜索覆盖、正文读取、仓库证据和 PDF 读取取决于用户工具；缺口会在 prompt 和诊断里标为 warning / 待验证。
`A / Recommended`	`Exa MCP + Firecrawl MCP + GitHub MCP + DeepWiki MCP`	推荐给外部用户的一键配置组合，覆盖多源检索、网页正文、仓库/issue/PR 读取和代码知识库分析。
`S / Best`	`Z.AI Coding Plan / web-search-prime / web-reader / zread`	最佳体验路径；配置 `ZAI_CODING_CN_API_KEY` 后启用联网检索硬规则。

能力检测覆盖 web search / web reader / repo search / read file / repo structure / PDF reader / GitHub access。缺少 reader 时，结论可靠性会下降；缺少 repo search 或 GitHub access 时，开源项目分析会弱；缺少 PDF reader 时，论文和白皮书类资料只能标为待验证。诊断只读取 .mcp.json 和环境变量，不主动访问外部服务或消耗额度。

如果后续接入其他 MCP server，仍然可以继续使用 mcp({ search: ... }) / mcp({ tool, args }) 代理方式按需发现和调用工具；当前默认是“6 个直出 + 4 个兜底（含 Vision MCP）”的工具面组合。

8. 配置飞书通道（可选）

让 Agent 通过飞书接收和回复消息，无需公网域名、无需加密配置：

a) 创建飞书应用

前往飞书开放平台创建自建应用
添加「机器人」能力
开发配置 → 权限管理：如果要让 Agent 回传图片或文件，额外开通 im:resource:upload（或 im:resource）
事件订阅 → 选择「使用长连接接收」
订阅 im.message.receive_v1 事件
发布应用

b) 填入配置

编辑 .env：

FEISHU_APP_ID=cli_xxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxx
# 首次绑定唯一飞书主人；pnpm run setup 的飞书模式会自动生成
FEISHU_OWNER_BOOTSTRAP_TOKEN=请替换为随机长令牌
# 可选：覆盖 /code 默认项目根目录
# CODING_PROJECTS_ROOT=/path/to/your/repos

FEISHU_APP_ID / FEISHU_APP_SECRET 只用于应用身份鉴权。FEISHU_OWNER_BOOTSTRAP_TOKEN 只用于首次绑定唯一主人，不能发送到群聊或提交到 Git；绑定成功后可从 .env 删除。飞书图片消息里的 image_key、文件消息里的 file_key 都不需要手工配置，它们是在上传资源到飞书后由接口动态返回的。

c) 启动后自动连接

pnpm run agent
# 看到 [feishu-channel] 长连接已启动 即成功

d) 首次绑定个人主人

飞书凭据已配置但未绑定主人时，pnpm run doctor 会失败，这是预期的安全门禁。使用准备作为唯一操作者的飞书账号发送：

/agent bind <FEISHU_OWNER_BOOTSTRAP_TOKEN>

绑定状态会写入本机 memory/feishu-access-policy.json，其中只保存飞书用户 ID 和绑定时间，不保存 bootstrap token。之后只有这个飞书账号可使用通道；其他账号的文本、图片、文件、/code 和 /skill 都会在下载附件或调用模型前被拒绝。若需要重新绑定，先停止 Agent，确认风险后删除该策略文件并设置新的 bootstrap token，再重启完成绑定。

e) 控制命令

也可手动控制：

命令	说明
`/feishu start`	手动启动长连接
`/feishu stop`	停止长连接
`/feishu status`	查看连接状态、长连接锁、队列当前/峰值、消息累计、重复消息缓存、卡片/图片/文件出站成功/失败、active model 和最近事件/错误
`/agent bind <token>`	仅首次绑定唯一飞书主人时使用

长连接已经启动后，也可以直接在飞书聊天里发送 /feishu status 查看同一份状态面板；这条控制命令不会进入最近对话上下文。

飞书端也支持确认式外部 skill 安装。支持 GitHub 仓库、/tree/<branch>/<path>、/blob/<branch>/.../SKILL.md 和 Raw GitHub SKILL.md；系统只安装静态 skill 文件，不执行脚本、不安装 npm package、不启用外部 extension。

skill 现在分成两层作用域：

user：my-pi-agent 自己维护的一层共享 skill，不等于整台机器任意 agent 的系统全局 skill
project：绑定到当前聊天里已经锁定的 /code 目标项目，只对那个项目的后续 coding workflow 生效

飞书端图片生成使用独立命令分流，不进入普通 AgentSession。生成结果会先保存到 memory/generated-images/，再上传为飞书图片消息：

桌面 Web 控制台的自然语言图片请求会走 baoyu-cover-image 专用路径，提示词与图片分别落到 cover-image/<topic>/prompts/ 和 cover-image/<topic>/cover.png，不会让普通 AgentSession 临时搜索图片 MCP。

飞书图片消息的识别则优先走独立 VISION_* 配置：默认使用 SiliconFlow zai-org/GLM-4.5V 输出结构化截图理解结果，再整理成中文回复；如果没配视觉 key，会回退到当前 active model 的多模态能力。

如果用户发送的是同一条富文本消息里的“图片 + /code ... 文本”，通道会先提取富文本中的 image_key，补做一次附图理解，再把这份附图上下文拼进本次 coding workflow 的 query；这样 coordinator 能直接看到截图里的列表、字段、按钮和标注，而不是只看到文字需求。

图片生成命令：

飞书消息	说明
`/image <图片描述>`	使用默认尺寸生成图片
`/img <图片描述>`	`/image` 的短别名
`/image <图片描述> --size 16:9`	指定尺寸；支持 `1280x1280`、`1024x1024`、`16:9`、`9:16`、`4:3`、`3:4`

Coding workflow 命令：

飞书消息	说明
`/code <项目名或路径>`	锁定当前聊天的 coding 项目上下文
`/code <需求>`	若当前聊天已锁定项目，实现类请求先走只读 coordinator 生成计划；纯 review/盘点类请求仍直接停在 coordinator 审查
`/code confirm <计划编号>`	确认当前聊天的待执行计划，才启动 coordinator → workers(parallel) → reviewers(parallel) → verifier
`/code cancel <计划编号>`	取消当前聊天的待执行计划，不创建任务或修改代码
`/coding <需求>`	`/code` 的别名
`/codex <需求>`	兼容别名，也会进入同一条 coding workflow
`/code` 口语化需求	需求里直接提到项目名或当前 `CODING_PROJECTS_ROOT` 下的绝对路径时，也会尝试自动识别
`/code` 多行头部	仍支持 `目录:` / `cwd:`、`参考目录:` / `reference:`、`验收:` / `verify:`、`项目:`、`概况:`、`任务:`，但都不是必填
`/code` 单行前缀头部	行首也支持 `目录:` / `项目:` / `参考目录:` 这类单值字段，后面可直接续写自然语言需求
飞书上传 `.md/.markdown` 文件后再发 `/code`	最近上传的接口文档会作为只读上下文自动带入 coding workflow

示例：

/code claude-code-sourcemap

/code
参考目录: ../agentos-openclaw-real-smoke-20260420-4imk9z
验收: npm run build

先写 spec，再按模块推进修复订单筛选链路，最后独立验证。

/code 参考目录: /Users/xxxxxx/Documents/GitHub/agentos-openclaw-real-smoke-20260420-4imk9z 把这个项目中的后端代码分离出来，使用 golang 重构

参考目录: 只会作为只读对照上下文传给 workflow，不会替代真实写代码的 目录: / 当前锁定项目目录。适合“按前端仓库对照，去另一个后端仓库落实现”这类前后端分离场景。

如果后端已经给了一份 Markdown 接口对接文档，可以直接在飞书里上传 .md / .markdown 文件；通道会下载到 memory/feishu-attachments/，并在 24 小时内把最近一份同聊天上传的文档注入 /code 的上下文。后续只需要继续发 /code 按刚上传的接口文档完成前端对接 之类的需求，不需要把本地路径写进命令。为避免误把 Word/PDF/Excel 当成可读接口契约，当前只接受 Markdown 文件；其他格式会明确提示重新上传 Markdown。

默认项目根目录会取当前用户 Documents/GitHub。路径示例：macOS 是 /Users/xxxxxx/Documents/GitHub，Windows 是 C:/Users/xxxxxx/Documents/GitHub。如果你的仓库不在这里，在 .env 里配置 CODING_PROJECTS_ROOT=/你的仓库根目录 后重启 agent 即可。

项目路径识别会按当前运行平台处理：macOS/Linux 支持 /repo/path 风格，Windows 同时支持 team/repo、team\\repo、C:/Users/... 和 C:\\Users\\... 这几类常见输入。

如果当前聊天还没锁定项目，飞书会先追问项目名或路径，而不是直接开跑。实现类需求会先回一张只读计划卡：此阶段执行器禁用 bash、write、edit 和 MCP 扩展，计划卡会提供 30 分钟有效的确认或取消命令。只有确认后，才会回 ⏳ coding agent 准备中... 并随着步骤推进持续更新；实时进展会显示当前步骤的 Skill 候选，最后收敛成和 coding_agent_run 相同结构的工程化摘要。纯 review/盘点请求不需要确认，仍按原有只读 coordinator 流程完成。最终结果如果单张卡片放不下，通道会用第一段更新原卡片，并把剩余内容继续补发为后续卡片；若飞书交互卡片最后一次更新失败，通道会自动退化为补发最终结果消息，而不是把旧卡片永远停在“生成中”。

通过 skill、普通编排入口或 /code 验收生成的本地图片会自动桥接到飞书。对外产物统一保存到 outputs/：截图、浏览器下载、导出的 PDF/CSV/HTML/ZIP/TXT/JSON，以及最终要给用户下载的 Office 文件都放这里；cover-image/、memory/generated-office/ 和 memory/generated-images/ 作为图片/Office 历史或专用目录继续扫描。例如 verifier 通过 browser probe 或 chrome-devtools 生成截图，并把路径暴露在工具结果或回复里，最终回执会把目标项目目录下的截图上传为飞书图片消息。如果图片超过飞书 10MB 限制，仍会保留本地文件路径说明。

普通飞书会话、统一编排入口和 /code 里生成或下载的可交付文件也会自动桥接到飞书。涉及 Word / PowerPoint / Excel 时，子会话应先调用 officecli_officecli 执行 command=load_skill 加载匹配 skill，再继续用 officecli_officecli 执行创建、检查、改版、美化或导出；PPT 默认优先 pptx，融资/投资人 deck 优先 pitch-deck，跨页 Morph 动效优先 morph-ppt，Word 用 word，Excel 用 excel。通道会按“回复中的产物目录显式路径 → 本轮 tool result 产物路径 → 本轮开始后 outputs/ 新生成的文件”查找候选，最多补发 3 个文件消息；可补发文件必须位于 outputs/ 或历史兼容的 memory/generated-office/，避免把 AGENTS.md / README.md 这类项目说明误当附件。支持后缀包括 .doc/.docx/.xls/.xlsx/.ppt/.pptx/.pdf/.csv/.tsv/.html/.txt/.md/.markdown/.json/.xml/.zip；飞书单文件上限按 30MB 处理，空文件不会上传，.docx/.xlsx/.pptx 会用 Feishu stream 类型上传。

Skill 管理命令：

飞书消息	说明
`/skill install [--scope user\|project] <GitHub 地址>`	下载并校验外部 skill，返回确认 token；默认 `user`，显式 `--scope project` 时安装到当前绑定项目
`/skill confirm <token>`	确认安装到当前待确认的 scope
`/skill cancel <token>`	取消待确认安装或卸载
`/skill list`	查看当前可用 skill；同时显示安装器记录和当前激活 user 共享层里的本地目录 skill
`/skill info <name> [--scope user\|project]`	查看 skill 来源、hash、路径和状态
`/skill remove <name> [--scope user\|project]`	发起卸载确认；这一步不会立刻删除
`/skill confirm-remove <token>`	确认卸载

默认不写 --scope 时，/skill install 会按 user scope 安装到当前配置的 my-pi-agent 共享层；如果显式写 /skill install --scope project <GitHub 地址>，则会安装到当前聊天已绑定 /code 项目的 <targetCwd>/.pi/skills/<name>/。当前聊天还没锁定项目时，--scope project 会直接拒绝。

当前项目 .pi/settings.json 可这样控制 user scope 用哪一层共享目录：

{
  "myPiAgent": {
    "sharedSkillStorage": "project"
  }
}

project（默认）：写入 my-pi-agent/.pi/user-skills/<name>/
machine：写入 ~/.my-pi-agent/user-skills/<name>/
legacy 兼容：旧的 my-pi-agent/.pi/skills/* 仍会作为 shared fallback 被发现，但新安装默认不再写进去
运行时发现规则：/code 和编排层默认只看 target project + 当前激活的 user 共享层
/skill list 会额外扫描当前激活 user 共享层里的本地目录 skill；未写入安装记录的项可以被运行时发现，但暂不能用 /skill info/remove 管理
/skill remove 只生成确认 token；发送 /skill confirm-remove <token> 后，已卸载的安装器记录才会从 /skill list 的可用清单里消失
info/remove 的 user 视角只操作当前激活的那一层安装记录，不会把 project 层和另一套 user 层混在一起
记录、详情和 prompt inventory 会标注 [project] / [user] 来源，便于区分 skill 是从哪里来的

如果 GitHub Contents API 返回 403 rate limit exceeded，安装器会优先回退到仓库归档下载；未命中回退条件时，可以在 .env 里配置 GITHUB_TOKEN。它既能提高 skill-installer 的 GitHub API 限额，也会被默认 GitHub MCP 复用做远程鉴权。

内置工具

工具	用途
`run`	自动编排（分析→拆解→执行）
`run_diagnose`	按 `runId` 查看某次编排/工作流运行的结构化诊断轨迹
`swarm_resume`	按 `swarmRunId` 恢复 SQLite swarm run，跳过已完成 worker，认领并执行剩余 task
`coding_agent_run`	职责化 coding workflow：实现类请求默认走 spec/plan → workers → reviewers → verifier；低风险小任务自动收敛为 spec/plan → workers → verifier；纯 review/盘点类请求停在 coordinator 审查；实现失败时最多自动回流 2 轮修复；同时写入 `swarm-coding-<taskId>` substrate run 供审计
`deep_research_capability`	只读诊断当前 Deep Research MCP 能力等级，输出 Basic / Recommended / Best、B/A/S、缺口影响和推荐配置模板
`project_scout`	Scout 式仓库侦察：根据 query 输出高置信 manifest/doc/code 线索，帮助在实现前快速收敛入口与范围
`project_semantic_query`	LSP-lite 语义查询：对 TS/JS 执行 definition / references / hover，定位符号定义、引用链和类型信息
`task_create`	手动创建多步骤长任务
`task_status`	查看任务状态
`task_diagnose`	查看任务最近一次或指定运行的结构化诊断轨迹
`task_control`	pause / resume / cancel / retry
`image_generate`	统一图片生成入口，供后续图片类 skill 调用
`mcp`	发现和调用外部 MCP server 工具
`remember`	保存到短时记忆
`remember_long`	直接保存到长时记忆
`recall`	读取记忆
`save_context`	保存工作上下文

内置命令

命令	说明
`/prefs`	查看长期记忆
`/short`	查看短期记忆（待同步）
`/sync`	手动触发记忆同步
`/tasks`	查看所有任务
`/task <id>`	查看任务详情
`/taskdiag <id>`	查看任务最近一次运行的诊断轨迹
`/rundiag <runId>`	按运行 ID 查看诊断轨迹
`/schedule`	查看定时任务状态
`/prompts`	查看 Prompt 模板版本
`/feishu start/stop/status`	Pi 会话内飞书通道控制；飞书聊天内也可发送 `/feishu status` 查看连接锁、队列、幂等缓存和最近错误

示例对话

你: 帮我记住，我喜欢用 conventional commits 格式
Agent: ✓ 已记住: [workflow] 喜欢 git commit message 用 conventional commits 格式

你: 帮我调研 Temporal 和 BullMQ 的区别
Agent: [自动 research → 并行搜索 → 综合分析 → 返回对比报告]

你: /code 重构 utils 模块，加上单元测试
Agent: [coding workflow → Coordinator 规格拆解 → Workers 实施 → Reviewers 审查 → Verifier 验证，并写入 swarm-coding-* 审计 run]

🔧 扩展与替换

运行时仍通过工厂和接口替换 analyzer、router、decomposer、task store、executor 等组件。具体边界和示例见 docs/runtime-architecture.md。

🗺️ 版本路线

版本	内容	状态
v0.1 基础骨架	仓库上下文、项目配置、记忆工具、会话记忆注入	✅ 已完成
v0.2 任务系统	`run` / `task_create` / `task_status` / `task_control`、JSON 队列、断点续跑、重试	✅ 已完成
v0.3 编排重构	自研 Orchestrator 作为控制面，Dispatcher 分派 shell / Pi AgentSession，兼容混合步骤	✅ 已完成
v0.4 飞书通道	`.env` 配置、WebSocket 长连接、文本/富文本/图片处理、卡片式回复	✅ 已完成
v0.5 稳定性与回归	固化关键测试场景、建立最小回归基线、整理决策记录、MCP 外部工具接入和使用文档	✅ 已完成
v0.6 外部 Skill 安装	飞书端 `/skill` 命令、GitHub 下载校验、确认式安装、记录和卸载	✅ 已完成
v0.7 图片生成能力	统一 `image_generate` 工具、SiliconFlow Z-Image-Turbo provider、飞书 `/image` 回传图片	✅ 已完成
v0.8 Coding Agent Workflow	`coding_agent_run`、implementationPlan、workers/reviewers 并行 lane、worker worktree 隔离合回、verification runner、warning 分级、requirement anchor guard	✅ 已完成
v0.9 个人版 Beta	单主人访问控制、`/code` 计划审批、数据治理、CLI/Web/Electron 本机只读控制台	🚧 进行中
vNext Agentic Engineering Loop	`engineering-loop` 企业入口、`agentic-sdlc-loop` workflow、公司 Agent 输出接入、拆分校验、测试合同、sandbox execution layer、证据归档和回写	📋 待规划
vNext 工作流扩展	真实链路持续 dogfooding、Telegram/其他通道、双模型互审、Temporal 等分布式调度评估	📋 待规划

License

Private — 内部演进项目

Navigation Menu

Repository files navigation

my-pi-agent

✨ 核心能力

🧭 文档导航

🧩 当前边界

🚀 快速开始

1. 安装

2. 配置模型

3. Docker 一键启动

4. 首次 setup（推荐）

5. 启动

6. 运行质量检查

7. 配置外部 MCP（可选）

8. 配置飞书通道（可选）

内置工具

内置命令

示例对话

🔧 扩展与替换

🗺️ 版本路线

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.opencode		.opencode
.pi		.pi
apps		apps
docker		docker
docs		docs
packages		packages
scripts		scripts
types		types
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.mcp.json		.mcp.json
AGENTS.md		AGENTS.md
Dockerfile		Dockerfile
README.md		README.md
docker-compose.yml		docker-compose.yml
eslint.config.js		eslint.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

my-pi-agent

✨ 核心能力

🧭 文档导航

🧩 当前边界

🚀 快速开始

1. 安装

2. 配置模型

3. Docker 一键启动

4. 首次 setup（推荐）

5. 启动

6. 运行质量检查

7. 配置外部 MCP（可选）

8. 配置飞书通道（可选）

内置工具

内置命令

示例对话

🔧 扩展与替换

🗺️ 版本路线

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages