pi-profile-switch 0.4.5 → 0.4.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +72 -21
  2. package/README.zh-CN.md +72 -21
  3. package/bin/postinstall.js +3 -2
  4. package/examples/example.json +37 -0
  5. package/examples/profiles.json +7 -31
  6. package/package.json +2 -3
  7. package/defaults/profiles.json +0 -18
package/README.md CHANGED
@@ -2,9 +2,7 @@
2
2
 
3
3
  [English](README.md) | [中文](README.zh-CN.md)
4
4
 
5
- Named profiles for [Pi](https://github.com/badlogic/pi-mono). A profile references a set of existing skills, extensions, MCP servers, and tools — switch between them in the same Pi process, without restarting.
6
-
7
- Use a lean read-only profile for code review, a full-powered one for implementation, a minimal one for a quick question — all against the same installed resources.
5
+ Named profiles for [Pi](https://github.com/badlogic/pi-mono). A profile is a named capability bundle you define: skills, extensions, MCP servers, tools (including tools exposed by MCP servers and extensions), model defaults, and extra system-prompt instructions. Switch bundles inside a running Pi session — no restart.
8
6
 
9
7
  ## Install
10
8
 
@@ -20,33 +18,92 @@ Requires [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) (in
20
18
  # Launch with the built-in default profile (all resources, plain Pi behavior)
21
19
  pi-profile
22
20
 
23
- # Launch with a named profile
24
- pi-profile review
21
+ # Launch with the seeded read-only ask profile
22
+ pi-profile ask
25
23
 
26
24
  # Anything after -- is passed to pi verbatim
27
- pi-profile review -- --model openai/gpt-5.4
25
+ pi-profile ask -- --model openai/gpt-5.4
28
26
  ```
29
27
 
30
- Define profiles in `~/.pi-profile-switch/profiles.json` (global, fallback to `~/.pi/agent/profiles.json` for migration; custom root via `PI_PROFILE_SWITCH_DIR`) or `<project>/.pi/profiles.json` (project, trusted projects only):
28
+ ## Define your own profiles
29
+
30
+ Profiles live in two JSON files, both optional:
31
+
32
+ | File | Scope |
33
+ | --- | --- |
34
+ | `~/.pi-profile-switch/profiles.json` | Global, all projects. `PI_PROFILE_SWITCH_DIR` overrides the root; `~/.pi/agent/profiles.json` is read as a legacy fallback for migration. |
35
+ | `<project>/.pi/profiles.json` | Project-level, trusted projects only. |
36
+
37
+ Create or change a profile by editing the JSON directly — schema: [`schemas/profiles.schema.json`](schemas/profiles.schema.json).
38
+
39
+ On install, pi-profile-switch seeds the global file with a starter **`ask`** profile — read-only Q&A and code exploration. It assumes nothing about your setup; edit or delete it freely:
31
40
 
32
41
  ```json
33
42
  {
34
43
  "schemaVersion": 1,
35
44
  "profiles": {
36
- "review": {
37
- "label": "Code review",
38
- "skills": ["code-review"],
39
- "mcp": ["github"],
40
- "tools": ["read", "grep", "find", "bash"],
41
- "instructions": "Review only; do not modify files."
45
+ "ask": {
46
+ "label": "Ask & Discuss",
47
+ "description": "Read-only Q&A and code exploration; no file modifications or command execution",
48
+ "skills": [],
49
+ "extensions": [],
50
+ "tools": ["read", "grep", "find", "ls"],
51
+ "instructions": "You are in read-only discussion mode. Answer questions and explain code without modifying any files or running shell commands."
42
52
  }
43
53
  }
44
54
  }
45
55
  ```
46
56
 
47
- Profiles **reference** resources by name — they never copy them. Installed packages and files in standard locations are discovered automatically; no registration needed. Full schema with more examples: [`examples/profiles.json`](examples/profiles.json).
57
+ One profile can use every field at once. This example `impl` profile loads the TDD skill, the mcp-scripting skill (shipped by pi-mcp-adapter), and your internal skills; wires up two MCP servers; allows the built-in tools plus both servers' MCP tools by glob; and pins the model and standing instructions:
48
58
 
49
- On install, pi-profile-switch seeds `~/.pi-profile-switch/profiles.json` with a starter **`ask`** profile — read-only Q&A and code exploration (`read`/`grep`/`find`/`ls`, no skills, extensions, or MCP). It assumes nothing about your setup; edit or delete it freely.
59
+ ```json
60
+ {
61
+ "schemaVersion": 1,
62
+ "profiles": {
63
+ "impl": {
64
+ "label": "Implementation",
65
+ "description": "Full-powered implementation profile: every available field, pinned model",
66
+ "skills": [
67
+ "tdd",
68
+ "internal-*",
69
+ "mcp-scripting"
70
+ ],
71
+ "extensions": [
72
+ "pi-mcp-adapter"
73
+ ],
74
+ "mcps": [
75
+ "github",
76
+ "linear"
77
+ ],
78
+ "tools": [
79
+ "read",
80
+ "grep",
81
+ "find",
82
+ "ls",
83
+ "bash",
84
+ "edit",
85
+ "write",
86
+ "mcp__*",
87
+ "github_*",
88
+ "linear_*"
89
+ ],
90
+ "defaultProvider": "anthropic",
91
+ "defaultModel": "claude-sonnet-4-5",
92
+ "defaultThinkingLevel": "high",
93
+ "instructions": "Prefer small, verifiable changes. Run the test suite before claiming completion."
94
+ }
95
+ }
96
+ }
97
+ ```
98
+
99
+ How fields resolve:
100
+
101
+ - `skills`, `extensions`, `mcps`, `tools` take names or globs (e.g. `"internal-*"`) referencing resources you already installed or configured — profiles never copy them. Installed packages and files in standard locations are discovered automatically; no registration needed.
102
+ - `tools` expands against Pi's live tool registry — built-ins, extension-provided tools, and tools exposed by MCP servers. MCP tools are registered as `mcp__<server>` (proxy) and `<server>_<tool>` (direct tools, the adapter's default `toolPrefix`), so globs like `mcp__*` and `github_*` cover them.
103
+ - `mcps` references servers from your pi-mcp-adapter configuration; connection details stay in the adapter's own config.
104
+ - Any field you omit keeps plain Pi behavior.
105
+
106
+ The files in [`examples/`](examples/) mirror the two profiles above: `profiles.json` is the seeded starter, `example.json` the full-field demo.
50
107
 
51
108
  ## Commands
52
109
 
@@ -62,12 +119,6 @@ In the TUI, the `/profile` command family manages everything in-session:
62
119
 
63
120
  All commands work in non-interactive modes (`--mode rpc|print|json`); CRUD wizards are TUI-only.
64
121
 
65
- ## Guarantees
66
-
67
- - **Reference, never copy** — profiles point at resources you already own and maintain.
68
- - **Pi-native** — anything a profile doesn't explicitly control keeps plain Pi behavior.
69
- - **Fail safe** — untrusted project directories are never read; a failed switch rolls back to the last working configuration.
70
-
71
122
  ## Docs
72
123
 
73
124
  - [Architecture](docs/architecture/overview.md) · [ADRs](docs/adr/) · [Glossary](CONTEXT.md) (Chinese)
package/README.zh-CN.md CHANGED
@@ -2,9 +2,7 @@
2
2
 
3
3
  [English](README.md) | [中文](README.zh-CN.md)
4
4
 
5
- [Pi](https://github.com/badlogic/pi-mono) 的命名 profile 扩展。一个 profile 引用一组已存在的 skills、extensions、MCP server 和 tools，并在同一 Pi 进程内切换，无需重启。
6
-
7
- 代码评审用精简的只读 profile，实现需求用全量 profile，临时提问用最小 profile——全部基于同一套已安装的资源。
5
+ [Pi](https://github.com/badlogic/pi-mono) 的命名 profile 扩展。一个 profile 是你自定义的命名能力组合：skills、extensions、MCP server、tools（包括 MCP server 和 extension 提供的工具）、默认模型，以及追加到系统提示词的 instructions。在同一个运行中的 Pi 会话里切换这些组合，无需重启。
8
6
 
9
7
  ## 安装
10
8
 
@@ -20,33 +18,92 @@ npm install -g pi-profile-switch
20
18
  # 使用内建 default profile 启动（全量资源，等同原生 Pi）
21
19
  pi-profile
22
20
 
23
- # 使用指定 profile 启动
24
- pi-profile review
21
+ # 使用安装时播种的只读 ask profile 启动
22
+ pi-profile ask
25
23
 
26
24
  # -- 后面的参数原样传给 pi
27
- pi-profile review -- --model openai/gpt-5.4
25
+ pi-profile ask -- --model openai/gpt-5.4
28
26
  ```
29
27
 
30
- 在 `~/.pi-profile-switch/profiles.json`（全局，支持 `PI_PROFILE_SWITCH_DIR` 环境变量自定义，向下兼容 `~/.pi/agent/profiles.json`）或 `<项目>/.pi/profiles.json`（项目级，仅限已信任项目）中定义 profile：
28
+ ## 自定义 profile
29
+
30
+ profile 定义在两个 JSON 文件中，均可选：
31
+
32
+ | 文件 | 作用域 |
33
+ | --- | --- |
34
+ | `~/.pi-profile-switch/profiles.json` | 全局，对所有项目生效。`PI_PROFILE_SWITCH_DIR` 可自定义根目录；`~/.pi/agent/profiles.json` 作为遗留路径向下兼容，用于迁移。 |
35
+ | `<项目>/.pi/profiles.json` | 项目级，仅对已信任项目生效。 |
36
+
37
+ 直接编辑 JSON 即可创建或修改 profile——schema 见 [`schemas/profiles.schema.json`](schemas/profiles.schema.json)。
38
+
39
+ 安装时，pi-profile-switch 会向全局文件播种一个初始 **`ask`** profile——只读的问答与代码走读模式。它不假设你安装过任何插件，可随意修改或删除：
31
40
 
32
41
  ```json
33
42
  {
34
43
  "schemaVersion": 1,
35
44
  "profiles": {
36
- "review": {
37
- "label": "Code review",
38
- "skills": ["code-review"],
39
- "mcp": ["github"],
40
- "tools": ["read", "grep", "find", "bash"],
41
- "instructions": "Review only; do not modify files."
45
+ "ask": {
46
+ "label": "Ask & Discuss",
47
+ "description": "Read-only Q&A and code exploration; no file modifications or command execution",
48
+ "skills": [],
49
+ "extensions": [],
50
+ "tools": ["read", "grep", "find", "ls"],
51
+ "instructions": "You are in read-only discussion mode. Answer questions and explain code without modifying any files or running shell commands."
42
52
  }
43
53
  }
44
54
  }
45
55
  ```
46
56
 
47
- Profile 只**引用**资源，从不复制资源。已安装的包和标准目录下的文件会被自动发现，无需注册。完整示例见 [`examples/profiles.json`](examples/profiles.json)。
57
+ 一个 profile 可以同时使用全部字段。下面这个 `impl` profile 示例加载 TDD skill、mcp-scripting skill（pi-mcp-adapter 自带）和你的内部 skills；接入两个 MCP server；tool 白名单用 glob 覆盖内建工具和这两个 server 的 MCP 工具；并钉住模型与常驻 instructions：
48
58
 
49
- 安装时，pi-profile-switch 会向 `~/.pi-profile-switch/profiles.json` 写入一个初始 **`ask`** profile——只读的问答与代码走读模式（仅 `read`/`grep`/`find`/`ls`，无 skill、extension 和 MCP）。它不假设你安装过任何插件，可随意修改或删除。
59
+ ```json
60
+ {
61
+ "schemaVersion": 1,
62
+ "profiles": {
63
+ "impl": {
64
+ "label": "Implementation",
65
+ "description": "Full-powered implementation profile: every available field, pinned model",
66
+ "skills": [
67
+ "tdd",
68
+ "internal-*",
69
+ "mcp-scripting"
70
+ ],
71
+ "extensions": [
72
+ "pi-mcp-adapter"
73
+ ],
74
+ "mcps": [
75
+ "github",
76
+ "linear"
77
+ ],
78
+ "tools": [
79
+ "read",
80
+ "grep",
81
+ "find",
82
+ "ls",
83
+ "bash",
84
+ "edit",
85
+ "write",
86
+ "mcp__*",
87
+ "github_*",
88
+ "linear_*"
89
+ ],
90
+ "defaultProvider": "anthropic",
91
+ "defaultModel": "claude-sonnet-4-5",
92
+ "defaultThinkingLevel": "high",
93
+ "instructions": "Prefer small, verifiable changes. Run the test suite before claiming completion."
94
+ }
95
+ }
96
+ }
97
+ ```
98
+
99
+ 字段解析规则：
100
+
101
+ - `skills`、`extensions`、`mcps`、`tools` 接受名称或 glob（如 `"internal-*"`），引用你已安装或已配置的资源——profile 从不复制资源。已安装的包和标准目录下的文件会被自动发现，无需注册。
102
+ - `tools` 针对 Pi 的实时工具注册表展开——内建工具、extension 提供的工具，以及 MCP server 暴露的工具。MCP 工具注册为 `mcp__<server>`（代理）和 `<server>_<tool>`（直接工具，adapter 默认 `toolPrefix`），因此 `mcp__*`、`github_*` 这类 glob 可以覆盖它们。
103
+ - `mcps` 引用 pi-mcp-adapter 配置中的 server；连接细节留在 adapter 自己的配置里。
104
+ - 未写的字段保持原生 Pi 行为。
105
+
106
+ [`examples/`](examples/) 中的两个文件与上面一一对应：`profiles.json` 是播种的初始 profile，`example.json` 是全字段演示。
50
107
 
51
108
  ## 命令
52
109
 
@@ -62,12 +119,6 @@ Profile 只**引用**资源，从不复制资源。已安装的包和标准目
62
119
 
63
120
  非交互模式（`--mode rpc|print|json`）下命令同样生效；CRUD 向导仅 TUI 可用。
64
121
 
65
- ## 保证
66
-
67
- - **引用而非复制**——profile 指向你自己拥有和维护的资源。
68
- - **Pi 原生**——profile 未显式控制的一切保持原生 Pi 行为。
69
- - **失败安全**——未信任的项目目录从不读取；切换失败回滚到上一份可用配置。
70
-
71
122
  ## 文档
72
123
 
73
124
  - [架构设计](docs/architecture/overview.md) · [ADR](docs/adr/) · [术语表](CONTEXT.md)
package/bin/postinstall.js CHANGED
@@ -4,7 +4,8 @@
4
4
  *
5
5
  * Runs at package install time (`npm install pi-profile-switch` / `pi install`).
6
6
  * Idempotent and conservative:
7
- * - Writes `defaults/profiles.json` to the profile-switch dir ONLY when no
7
+ * - Writes the shipped `examples/profiles.json` starter catalog to the
8
+ * profile-switch dir ONLY when no
8
9
  * catalog exists there yet (COPYFILE_EXCL; an existing file — including
9
10
  * one written concurrently — is never touched).
10
11
  * - Skips entirely when a legacy `~/.pi/agent/profiles.json` exists, because
@@ -22,7 +23,7 @@ import { homedir } from "node:os";
22
23
  import path from "node:path";
23
24
  import { fileURLToPath, pathToFileURL } from "node:url";
24
25
 
25
- const DEFAULT_TEMPLATE = fileURLToPath(new URL("../defaults/profiles.json", import.meta.url));
26
+ const DEFAULT_TEMPLATE = fileURLToPath(new URL("../examples/profiles.json", import.meta.url));
26
27
 
27
28
  /** Mirrors getProfileSwitchDir() in src/workspace.ts.
28
29
  * @param {NodeJS.ProcessEnv} env */
package/examples/example.json ADDED
@@ -0,0 +1,37 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "profiles": {
4
+ "impl": {
5
+ "label": "Implementation",
6
+ "description": "Full-powered implementation profile: every available field, pinned model",
7
+ "skills": [
8
+ "tdd",
9
+ "internal-*",
10
+ "mcp-scripting"
11
+ ],
12
+ "extensions": [
13
+ "pi-mcp-adapter"
14
+ ],
15
+ "mcps": [
16
+ "github",
17
+ "linear"
18
+ ],
19
+ "tools": [
20
+ "read",
21
+ "grep",
22
+ "find",
23
+ "ls",
24
+ "bash",
25
+ "edit",
26
+ "write",
27
+ "mcp__*",
28
+ "github_*",
29
+ "linear_*"
30
+ ],
31
+ "defaultProvider": "anthropic",
32
+ "defaultModel": "claude-sonnet-4-5",
33
+ "defaultThinkingLevel": "high",
34
+ "instructions": "Prefer small, verifiable changes. Run the test suite before claiming completion."
35
+ }
36
+ }
37
+ }
package/examples/profiles.json CHANGED
@@ -1,42 +1,18 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
3
  "profiles": {
4
- "review": {
5
- "label": "Code review",
6
- "description": "Read-heavy review workflow",
7
- "skills": [
8
- "code-review",
9
- "diagnosing-bugs"
10
- ],
11
- "extensions": [
12
- "pi-mcp-adapter"
13
- ],
14
- "mcps": [
15
- "github"
16
- ],
4
+ "ask": {
5
+ "label": "Ask & Discuss",
6
+ "description": "Read-only Q&A and code exploration; no file modifications or command execution",
7
+ "skills": [],
8
+ "extensions": [],
17
9
  "tools": [
18
10
  "read",
19
11
  "grep",
20
12
  "find",
21
- "bash"
22
- ],
23
- "instructions": "Review only; do not modify files."
24
- },
25
- "impl": {
26
- "label": "Implementation",
27
- "skills": [
28
- "tdd"
29
- ],
30
- "extensions": [
31
- "pi-mcp-adapter"
32
- ],
33
- "mcps": [
34
- "github",
35
- "linear"
13
+ "ls"
36
14
  ],
37
- "defaultProvider": "deepseek",
38
- "defaultModel": "deepseek-v4-pro",
39
- "defaultThinkingLevel": "high"
15
+ "instructions": "You are in read-only discussion mode. Answer questions and explain code without modifying any files or running shell commands."
40
16
  }
41
17
  }
42
18
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pi-profile-switch",
3
- "version": "0.4.5",
4
- "description": "Named profiles for Pi: reference skills, extensions, MCP servers, and tools per workflow, switched without restarting.",
3
+ "version": "0.4.8",
4
+ "description": "Named profiles for Pi: reference skills, extensions, MCP servers, and tools per workflow, switched without restarting. Install: npm install -g pi-profile-switch (not pi install).",
5
5
  "type": "module",
6
6
  "keywords": [
7
7
  "pi-package",
@@ -45,7 +45,6 @@
45
45
  },
46
46
  "files": [
47
47
  "bin",
48
- "defaults",
49
48
  "extensions",
50
49
  "src",
51
50
  "schemas",
package/defaults/profiles.json DELETED
@@ -1,18 +0,0 @@
1
- {
2
- "schemaVersion": 1,
3
- "profiles": {
4
- "ask": {
5
- "label": "Ask & Discuss",
6
- "description": "Read-only Q&A and code exploration; no file modifications or command execution",
7
- "skills": [],
8
- "extensions": [],
9
- "tools": [
10
- "read",
11
- "grep",
12
- "find",
13
- "ls"
14
- ],
15
- "instructions": "You are in read-only discussion mode. Answer questions and explain code without modifying any files or running shell commands."
16
- }
17
- }
18
- }