ygg-pi

通用 AI Agent — 8 场景 5 工作流，七层安全放行，审查引擎，记忆系统，并行 Agent

基于 pi coding agent 的 Extension 系统构建。

✨ 特性

• 🎯 8 个场景：代码开发、数据分析、写作助手、学习辅导、学术研究、办公效率、资料管理、生活助手
• 🔄 5 种工作流：React（编写修改）、Explore（分析研究）、Plan（规划设计）、Chat（闲聊问答）、Autopilot（全自动）
• 🛡️ 七层安全放行：路径沙箱 → 只读放行 → 意图匹配 → 信任积累 → 危险拦截 → 敏感保护 → 循环检测
• 🧠 记忆系统：用户级 + 项目级双层存储，自动学习偏好和约定
• 🔍 审查引擎：副模型独立审查（安全/正确/风格），流式输出
• ⚡ 并行 Agent：多任务并行执行，实时面板显示进度
• 🤖 子代理系统：自定义 Agent + Hooks 自动化
• 📊 多行状态栏：领域/工作流/模型/token/上下文进度/工具统计/任务列表
• 🛠️ 12 个自定义工具：任务管理、Web 搜索、文档读取、语法检查、学术搜索等
• 📚 23 个 Skill：写作系列、文档处理、创作工具等

📦 安装

前置条件

• Node.js 22+（需要 node:sqlite 支持）
• npm 或 pnpm

方式 1：npm 安装（推荐）

npm install -g @ygg-team/ygg-pi

安装完成后会自动执行 postinstall：

• 创建 ~/.ygg-pi/ 全局配置目录
• 生成默认 settings.json 和 permissions.json
• 复制 Skills 到 ~/.ygg-pi/skills/

方式 2：源码安装

# 1. 安装 pi coding agent
npm install -g @earendil-works/pi-coding-agent@0.83.0

# 2. 克隆项目
git clone https://gitee.com/yggxiaohuayuan/ygg-pi.git
cd ygg-pi

# 3. 安装依赖
npm install

# 4. 全局链接
npm link

🚀 使用

启动方式

# 方式 1：使用包装脚本（推荐，自动加载所有扩展）
ygg-pi

# 方式 2：指定会话名
ygg-pi --session my-project

# 方式 3：直接用 pi 加载扩展
pi -e ./extensions/*.ts -e ./extensions/tools/*.ts

# 方式 4：只加载部分扩展
pi -e ./extensions/safety.ts -e ./extensions/scene-router.ts

首次使用

1. 启动 ygg-pi
2. 输入 /domain 切换到你需要的场景（默认是代码开发）
3. 直接用自然语言描述任务，系统会自动分类工作流
4. 或者输入 /workflow 手动选择工作流

基本交互

# 直接描述任务（系统自动分类）
帮我分析一下这段代码的性能问题     → 自动路由到 explore 工作流
修复这个 TypeScript 编译错误       → 自动路由到 react 工作流
给我一个微服务架构方案             → 自动路由到 plan 工作流

# 手动切换场景
/domain                          → 弹框选择场景

# 手动切换工作流
/workflow                        → 弹框选择工作流

# 全自动执行
/autopilot 帮我重构这个模块，运行测试确保通过

🎯 场景系统

8 个场景，每个场景有不同的角色定义和工具集。

场景列表

场景	说明	特色工具
代码开发	全栈编程助手，精通 TypeScript/JavaScript/Python	read/write/edit/bash/grep/find/ls
数据分析	数据分析专家	+ db_query（SQLite 只读查询）
写作助手	写作润色专家	+ grammar_check（语法检查）
学习辅导	学习引导者（不直接给答案）	引导思考模式
学术研究	学术研究助手	+ scholar_search（论文检索）
办公效率	办公自动化专家	+ send_email + doc_read
资料管理	知识管理专家	完整工具集 + 记忆系统
生活助手	生活推荐助手	web_search/web_fetch

切换场景

/domain                    # 弹框选择
/domain 代码开发            # 直接指定（TODO：当前版本用弹框）

场景持久化到 .ygg-pi/settings.json 的 domain 字段，下次启动自动恢复。

🔄 工作流系统

5 种工作流，自动或手动切换。

工作流列表

工作流	触发场景	行为
react	修改/创建/调试/实现功能	思考→行动→观察循环，批量读改验证
explore	分析/理解/研究/调查	只读模式，逐模块深入，够用就停
plan	设计/规划/方案/架构	先用 task 创建任务列表，确认后逐个执行
chat	闲聊/问答/问候	纯对话，跳过复杂流程
autopilot	手动触发 /autopilot <任务>	全自动执行，跳过确认（危险命令仍拦截）

自动分类

系统使用 LLM 自动分类用户输入（5 秒超时），支持检测：

• [debug] 标记：用户报告 bug/错误 → 进入 debug 状态机
• [plan] 标记：用户请求方案/设计 → 进入 plan 状态机

手动切换

/workflow                   # 弹框选择
/workflow react             # 直接指定（TODO：当前版本用弹框）

工作流持久化到 .ygg-pi/settings.json 的 workflow 字段。

🛡️ 安全系统

七层放行漏斗

层0  路径沙箱        文件操作不可越出项目根目录
  ↓
层1  只读放行        read/grep/find/ls 无限制
  ↓
层2  意图匹配        用户含"写/修改/运行" → 放行对应工具
  ↓
层3  本轮复用        同工具+参数已确认 → 自动放行
  ↓
层4  信任积累        连续 2+ 次安全操作 → 低风险自动放行
  ↓
层5  危险拦截        rm -rf/sudo/chmod 777 → 弹框确认
  ↓
层6  敏感文件        修改 .env/package.json → 弹框确认
  ↓
层7  循环检测        同一调用 ≥4 次 → 拦截
  ↓
兜底  弹框确认       未命中以上 → 询问用户

自定义安全规则

编辑 ~/.ygg-pi/permissions.json：

{
  "dangerous": [
    "\\brm\\s+-rf?\\b",
    "\\bsudo\\b",
    "\\bchmod\\s+777\\b",
    "curl.*\\|.*sh"
  ],
  "sensitive": [
    ".env",
    "package.json",
    "tsconfig.json",
    ".gitignore"
  ],
  "trusted": [
    "^(npm|pnpm|yarn)\\s+(test|run|install)\\b",
    "^(git|tsc|eslint|prettier)\\s"
  ]
}

• dangerous：匹配这些正则的命令需要用户确认
• sensitive：修改这些文件需要用户确认
• trusted：匹配这些正则的命令自动放行

路径沙箱

文件操作默认限制在项目根目录内。访问项目外的目录时会弹框确认，确认后：

• 本次会话有效
• 当天有效（存储在 ~/.ygg-pi/trusted-paths.json）

Debug 状态机

当系统检测到用户报告 bug/错误时，自动进入 debug 模式：

诊断阶段（只读）
  ↓ ≥3 次只读操作 + 输出根因/修复方案
修复阶段（限制写入）
  ↓ ≤3 文件 × 50 行，每次改完需 tsc --noEmit 验证
汇总

Plan 状态机

当系统检测到用户请求方案/设计时，自动进入 plan 模式：

规划阶段（只读）
  ↓ 用 task 工具创建任务列表
执行阶段
  ↓ 逐个 task 执行
汇总

🧠 记忆系统

存储结构

• 用户级：~/.ygg-pi/memories.json（跨项目共享）
• 项目级：.ygg-pi/memories.json（仅当前项目）

记忆工具

# LLM 自动调用，也可手动触发
memory_search  { query: "偏好" }     # 搜索记忆
memory_save    { content: "...", category: "project" }  # 保存记忆

自动学习

系统通过 promptGuidelines 让 LLM 自动识别并保存：

• 用户偏好（"我喜欢..."、"偏好..."）
• 项目约定（"这个项目用..."、"约定..."）
• 重复指令（"以后..."、"总是..."）

记忆注入

每次对话开始时，scene-router 自动注入最近记忆（上限 500 字符）到 system prompt。

🔍 审查引擎

配置

在 ~/.ygg-pi/settings.json 或 .ygg-pi/settings.json 添加：

{
  "review": {
    "apiKey": "your-api-key",
    "model": "gpt-4o-mini",
    "baseURL": "https://api.openai.com/v1/chat/completions"
  }
}

使用

LLM 在生成代码后可自主决定调用 review 工具：

# LLM 自动调用，无需手动触发
review { text: "要审查的代码", context: "上下文说明" }

审查维度：

• 安全：是否泄露密钥/密码？是否有危险命令？
• 正确：逻辑是否自洽？引用是否准确？
• 风格：是否简洁？有无废话？

⚡ 并行执行

使用方式

LLM 自动将可并行的任务拆分调用：

parallel_execute {
  tasks: [
    "读取 src/utils.ts 的内容",
    "读取 src/config.ts 的内容",
    "搜索项目中所有 TODO 注释"
  ]
}

实时面板

执行过程中，status-bar 会显示实时进度：

▸ parallel_execute  2/3
  ✓ 1/3 读取 src/utils.ts  ·  2工具  ·  1轮  完成 3s
  ◉ 2/3 读取 src/config.ts  ·  执行中
  ○ 3/3 搜索 TODO  ·  等待

🤖 子代理系统

自定义 Agent

在 ~/.ygg-pi/agents/ 创建 .md 文件：

# 代码审查专家

description: 专注代码质量审查的子代理

你是一个代码审查专家。请仔细审查代码的安全性、可读性和性能。
发现问题时，给出具体的修复建议。

调用 Agent

LLM 自动决定是否需要调用子代理：

spawn_agent { agent: "代码审查专家", task: "审查 src/index.ts" }

Hooks 自动化

在 ~/.ygg-pi/hooks/ 创建 shell 脚本：

# ~/.ygg-pi/hooks/session-start.sh
echo "会话开始于 $(date)" >> ~/.ygg-pi/hooks.log

# ~/.ygg-pi/hooks/agent-end.sh
echo "任务完成" >> ~/.ygg-pi/hooks.log

支持的事件：

• session-start / session-end
• agent-start / agent-end
• pre-compact / post-compact

🛠️ 工具列表

核心工具

工具	说明	依赖
task	任务管理（list/create/update/delete/set_all）	—
parallel_execute	并行执行多个子任务	—
spawn_agent	调用子代理	—
review	副模型审查	需配置 review
memory_search	搜索记忆	—
memory_save	保存记忆	—
system_info	查询系统状态	git CLI

网络工具

工具	说明	依赖
web_search	三层降级搜索（博查→DuckDuckGo→Wikipedia）	博查 API Key（可选）
web_fetch	获取网页内容转 Markdown	—
scholar_search	学术论文检索（Semantic Scholar）	—

文档工具

工具	说明	依赖
doc_read	读取 Word/Excel/PPT 文档	python + python-docx/openpyxl/pptx
grammar_check	语法和拼写检查	LanguageTool API
send_email	发送邮件	需配置 SMTP
db_query	SQLite 只读查询	Node 22+ node:sqlite

📋 命令列表

场景和工作流

命令	说明
/domain（/领域）	切换场景（弹框选择）
/workflow（/工作流）	切换工作流（弹框选择）
/autopilot（/全自动）	全自动执行任务

会话管理

命令	说明
/sessions（/会话）	查看会话列表
/sessions new <名称>	创建新会话
/sessions switch <名称>	切换会话
/sessions rename <名称>	重命名当前会话
/sessions delete <名称>	删除会话

配置和工具

命令	说明
/config	查看/编辑 settings.json
/skill	查看和管理 Skill（启用/停用）
/init	全量阅读项目，生成/更新 AGENTS.md
/help	列出所有可用命令

pi 内置命令

命令	说明
/model	切换模型
/settings	打开设置菜单
/new	新建会话
/resume	恢复历史会话
/compact	手动压缩上下文
/tree	导航对话树
/copy	复制最后回复
/export	导出会话
/quit	退出程序

📚 Skill 系统

写作系列（12 个）

Skill	说明
story	写作主 Skill（大纲→章节→润色）
story-long-write	长篇写作
story-short-write	短篇写作
story-long-analyze	长篇分析
story-short-analyze	短篇分析
story-long-scan	长篇扫描
story-short-scan	短篇扫描
story-cover	封面设计
story-deslop	去 AI 味
story-import	导入分析
story-review	审稿
story-setup	初始化设定

文档处理（4 个）

Skill	说明
docx	Word 文档处理
xlsx	Excel 处理
pptx	PPT 处理
pdf	PDF 处理

创作工具（7 个）

Skill	说明
brainstorming	头脑风暴
frontend-design	前端设计指南
humanizer	文本人性化
skill-creator	Skill 创建器
superpowers	完整开发方法论
audit-website	网站审计
browser-cdp	浏览器控制

管理 Skill

/skill                    # 查看所有 Skill
# 选择一个 Skill 可以启用/停用
# 停用会创建 .disabled 文件，下次对话生效

📁 配置架构

三级优先级

项目 .ygg-pi/  >  全局 ~/.ygg-pi/  >  源码内置 configs/

• 项目级：.ygg-pi/ 目录，只影响当前项目
• 全局级：~/.ygg-pi/ 目录，影响所有项目
• 源码内置：configs/ 目录，包默认值，升级会覆盖

全局配置：~/.ygg-pi/

~/.ygg-pi/
├── settings.json            # 主配置（模型/审查/Web搜索/SMTP/记忆）
├── permissions.json         # 安全规则（dangerous/sensitive/trusted）
├── memories.json            # 用户级记忆（跨项目共享）
├── trusted-paths.json       # 信任路径（当天有效）
├── agents/                  # 自定义 Agent
│   └── 代码审查专家.md
├── hooks/                   # 自动化脚本
│   ├── session-start.sh
│   └── agent-end.sh
├── skills/                  # Skill（postinstall 自动复制）
│   ├── story/
│   ├── brainstorming/
│   └── ...
└── prompts/                 # 自定义 prompt（可选）
    ├── domains/
    └── workflows/

项目配置：.ygg-pi/

.ygg-pi/
├── settings.json            # 项目设置（domain/workflow/thinkingLevel）
├── memories.json            # 项目级记忆
├── sessions.json            # 命名会话索引
├── sessions/                # 会话存储目录
├── SAFETY_RULES.md          # 安全操作规则
└── prompts/                 # 项目级 prompt 覆盖（可选）
    ├── domains/
    └── workflows/

settings.json 完整配置

{
  "model": {
    "provider": "openai",
    "name": "gpt-4o",
    "apiKey": "sk-xxx",
    "baseURL": "https://api.openai.com/v1",
    "thinkingLevel": "high",
    "contextWindow": 131072
  },
  "review": {
    "apiKey": "sk-xxx",
    "model": "gpt-4o-mini",
    "baseURL": "https://api.openai.com/v1/chat/completions"
  },
  "webSearch": {
    "apiKey": "your-bocha-api-key",
    "baseURL": "https://api.bocha.cn/v1/web-search"
  },
  "smtp": {
    "host": "smtp.gmail.com",
    "port": 465,
    "secure": true,
    "user": "your-email@gmail.com",
    "pass": "your-app-password"
  },
  "embedding": {
    "provider": "openai",
    "model": "text-embedding-3-small",
    "apiKey": "sk-xxx",
    "baseURL": "https://api.openai.com/v1"
  },
  "memory": {
    "maxItems": 200
  }
}

🎨 状态栏

多行 Footer 布局

[代码开发] [auto/react] gpt-4o high  my-project  (main)
Context ████░░░░░░░░░░░░░░░░ 45.2k｜131k (34.5%)
read ×5 • bash ×3 • edit ×2
技能 brainstorming • frontend-design • skill-creator
任务 2/4
  ✓ 读取源码结构
  ✓ 分析依赖关系
  ◉ 编写测试用例
  ○ 更新文档

Widget 区域

• 上方 Widget：当前任务统计（输入/输出/耗时/LLM 调用次数）
• 下方 Widget：Session 累计统计（输入/输出/缓存命中率/LLM 调用次数）

🔧 开发

源码结构

ygg-pi/
├── bin/ygg-pi.js                # 包装脚本：读配置，收集扩展，启动 pi
├── configs/                     # 源码内置默认值
│   ├── SYSTEM.md                # 通用系统提示词
│   ├── settings.json            # 默认配置
│   ├── permissions.json         # 默认安全规则
│   └── prompts/
│       ├── domains/             # 8 个场景 prompt
│       └── workflows/           # 21 个工作流 prompt
├── extensions/                  # 12 个 Extension
│   ├── safety.ts                # 七层安全 + debug/plan 状态机
│   ├── scene-router.ts          # 场景路由 + prompt 注入
│   ├── intent-classifier.ts     # LLM 自动分类
│   ├── reviewer.ts              # 审查工具
│   ├── parallel.ts              # 并行执行
│   ├── memory.ts                # 记忆系统
│   ├── session-mgr.ts           # 会话管理
│   ├── agents-hooks.ts          # 子代理 + Hooks
│   ├── header.ts                # 启动面板
│   ├── chinese-autocomplete.ts  # 命令补全中文化
│   ├── commands.ts              # /help + /skill
│   ├── status-bar.ts            # 多行状态栏
│   ├── tools/                   # 11 个工具
│   │   ├── init.ts
│   │   ├── config.ts
│   │   ├── task-manager.ts
│   │   ├── web-search.ts
│   │   ├── web-fetch.ts
│   │   ├── system-info.ts
│   │   ├── db-query.ts
│   │   ├── doc-reader.ts
│   │   ├── email.ts
│   │   ├── grammar-check.ts
│   │   └── scholar-search.ts
│   └── utils/
│       ├── paths.ts             # 三级查找 + JSON 读写
│       └── cmd-log.ts           # 命令输出
├── skills/                      # 23 个 Skill
├── scripts/postinstall.js       # npm postinstall
├── tests/extensions-test.ts     # 31 项集成测试
└── docs/COMMENT_SPEC.md         # 注释规范

代码规范

• 每个 Extension export default 一个函数，接收 ExtensionAPI
• 入口必须 try-catch，异常用 ctx.ui.notify 通知
• 工具参数用 TypeBox schema
• 跨 Extension 通信用 pi.events.emit/on（前缀 ygg:）
• 文件操作通过 utils/paths.ts 的 findFile/readJson/writeJson

编译检查

npx tsc --noEmit

运行测试

npx tsx tests/extensions-test.ts

⚠️ 注意事项

1. pi 版本锁定 0.83.0，升级前在测试项目验证
2. Extension 独立加载，一个失败不影响其他
3. configs/ 是内置默认值，自定义放 ~/.ygg-pi/ 或 .ygg-pi/
4. debug 修复阶段限制：≤3 文件 × 50 行，每次 tsc 验证
5. autopilot 不跳过危险拦截，rm -rf 等仍会拦截
6. web_search 三层降级：博查 → DuckDuckGo → Wikipedia
7. parallel_execute 子 session 独立，结束后 dispose
8. 会话文件锁：PID 写入 .lock，防止多实例冲突

📖 最佳实践

代码开发

# 1. 切换到代码场景
/domain 代码开发

# 2. 描述任务
帮我重构 src/utils.ts，提取公共函数，添加单元测试

# 3. 系统自动：
#    - 分类为 react 工作流
#    - 读取文件分析结构
#    - 逐步重构
#    - 运行 tsc --noEmit 验证
#    - 汇报改动

调试 Bug

# 直接描述错误
运行 npm test 报错：TypeError: Cannot read property 'xxx' of undefined

# 系统自动进入 debug 模式：
# 1. 诊断阶段：读取相关文件，定位根因
# 2. 输出诊断报告和修复方案
# 3. 修复阶段：限制性修改
# 4. 验证修复

规划设计

# 描述需求
给我一个微服务架构方案，需要支持用户认证、订单管理、支付处理

# 系统自动进入 plan 模式：
# 1. 规划阶段：分析需求，创建任务列表
# 2. 确认后逐个执行

并行处理

# 描述多个独立任务
同时帮我：1) 分析 src/a.ts 的依赖 2) 检查 src/b.ts 的类型错误 3) 搜索项目中的 TODO

# 系统自动拆分并行执行

🤝 贡献

1. Fork 项目
2. 创建功能分支
3. 提交改动
4. 推送到分支
5. 创建 Pull Request

📄 许可证

MIT