@d3ara1n/pi-model-roles 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 Model role configuration library for [pi](https://github.com/earendil-works/pi) extensions.
 
-Defines named model roles (e.g. "heavy", "fast", "side") and resolves them to pi `Model` instances with API key and headers.
+Defines named model roles (e.g. "heavy", "fast", "utility") and resolves them to pi `Model` instances with API key and headers.
 
 ## What it does
 
@@ -24,14 +24,15 @@ Built-in defaults use `model: null` (use pi's current model, don't switch):
 
 | Role | model | thinking | Description |
 |------|-------|----------|-------------|
-| `default` | null | medium | Daily coding |
-| `heavy` | null | high | Architecture, deep debugging |
-| `fast` | null | off | Quick edits, simple Q&A |
+| `default` | null | medium | Regular dev tasks: new features, code edits, code review, adding tests, general debugging, single-file changes |
+| `heavy` | null | high | Deep-thinking tasks: cross-file refactoring, architecture design, complex bug debugging, performance optimization, security analysis, DB schema changes, multi-module migrations |
+| `fast` | null | low | Simple deterministic tasks: one-line edits, formatting, simple Q&A, doc lookups, git operations, confirmations |
+| `utility` | null | off | Lightweight utility tasks: routing, commit gen, title summarization |
 
 `model: null` means "keep using whatever model pi currently has".
 Only `thinking` level differs between roles by default.
 
-Custom roles (e.g. `side` for scout) can be added freely — any role name works:
+Custom roles can be added freely — any role name works:
 
 ## Configuration
 
@@ -48,11 +49,10 @@ Override specific roles in `~/.pi/agent/settings.json`:
         "model": "google/gemini-2.5-flash",
         "thinking": "off"
       },
-      // Custom role for scout's side agent
-      "side": {
+      // Lightweight utility tasks (routing, commit generation, etc.)
+      "utility": {
         "model": "deepseek/deepseek-v4-flash",
-        "thinking": "off",
-        "hidden": true
+        "thinking": "off"
       }
     },
     "defaultRole": "default"
@@ -63,6 +63,13 @@ Override specific roles in `~/.pi/agent/settings.json`:
 User settings **merge** with built-in defaults: only override roles you want to change.
 You can also add entirely new roles.
 
+### Hidden roles
+
+Roles with `hidden: true` (like `utility` by default) are excluded from scout's role
+selection list — the side agent won't suggest switching to them. They can still be
+used directly by name (e.g. as `sideAgentRole` in scout config) and resolved via
+`resolveRole()` / `resolveRoleAsync()`.
+
 ### Role fields
 
 | Field | Type | Default | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-model-roles",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Model role configuration library for pi extensions — defines named model roles and resolves them to Model instances",
   "main": "src/index.ts",
   "types": "src/types.ts",

package/src/defaults.ts

@@ -1,8 +1,8 @@
 /**
  * Built-in default role definitions.
  *
- * Only universal roles are built-in. Scout/subagent-specific roles
- * (like "side") are left for users to define — modelRoles accepts
+ * Only universal roles are built-in. Plugin-specific roles
+ * are left for users to define — modelRoles accepts
  * any custom role name.
  *
  * model=null means "use pi's current model, don't switch".
@@ -13,17 +13,23 @@ import type { RoleConfig } from "./types.ts";
 export const BUILTIN_DEFAULT_ROLES: Record<string, RoleConfig> = {
   default: {
     model: null,
-    description: "日常编码，速度和质量平衡",
+    description: "常规开发任务：编写新功能、修改现有代码、代码审查、添加测试、一般性调试、文件级别的修改",
     thinking: "medium",
   },
   heavy: {
     model: null,
-    description: "架构设计、深度调试、复杂迁移",
+    description: "需要深度思考的任务：跨文件重构、架构设计、复杂 bug 调试、性能优化、安全分析、数据库 schema 变更、涉及多个模块的迁移",
     thinking: "high",
   },
   fast: {
     model: null,
-    description: "快速修改、简单问答",
+    description: "简单确定性的任务：一行修改、格式调整、简单问答、文档查阅、git 操作、确认类回复",
+    thinking: "low",
+  },
+  utility: {
+    model: null,
+    description: "轻量辅助：模型路由、commit 生成、标题摘要等（hidden）",
     thinking: "off",
+    hidden: true,
   },
 };