pi-harness-factory

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# pi-harness-factory

Create, switch, and manage functional harness profiles for Pi Coding Agent.

## Concept

`pi-harness-factory` turns Pi into a project-local harness factory. A harness is a compiled working mode: tool access, mutation scope, validation strictness, safety gates, workflow rules, UI label, memory hints, recommended Pi packages, and capabilities.

The goal is not just to pick a persona. The factory helps you answer:

> What should the agent be allowed to do, how strict should it be, and what safety checks should apply for this project?

## Install

Try from a local checkout without installing permanently:

```bash
pi -e ./
```

Install from GitHub:

```bash
pi install git:github.com/kswift1/pi-harness-factory
```

Install from npm:

```bash
pi install npm:pi-harness-factory
```

## Quick start

Install the package, then restart Pi or run `/reload` in an existing Pi session so the `/factory` command is registered:

```bash
pi install npm:pi-harness-factory
```

Then run inside Pi:

```text
/factory
/factory list
/factory use tdd
```

With the bundled `tdd` profile active, Pi receives a strict coder harness: broad refactor scope, `Always` validation strictness, `Strict` safety gates, and `Plan then act` autonomy. In practice it plans before edits, validates after edits, summarizes changes, and asks before secret access, dangerous commands, deletes, or git push.

## Main menu

Run:

```text
/factory
```

The factory opens a menu:

```text
Use a harness
Create a harness
Current harness
Manage harnesses
```

### Use a harness

Opens an interactive card browser. Cards summarize each harness by functional behavior:

- mode / role
- allowed tools
- validation strictness
- mutation scope
- safety level
- confirmations
- workflow rules

You can also use direct commands:

```text
/factory browse
/factory list
/factory pick <profile-id>
/factory use <profile-id>
```

### Create a harness

Creates a project-local harness with a guided flow:

1. Choose role
   - Coder
   - Reviewer
   - Researcher
   - DevOps
   - PM / Writer
   - Custom
2. Choose role preset
   - Safe implementation
   - Strict TDD
   - Read-only review
   - Evidence researcher
   - Release operator
3. Customize harnessing axes
   - mutation scope
   - validation strictness
   - safety gates
   - autonomy
   - output style
4. Preview compiled rules
5. Save only or Save & Activate

Generated profiles are saved under:

```text
.pi/harness-factory/profiles/<profile-id>.json
```

### Current harness

Shows the active harness and the rules currently affecting Pi:

- persona / role summary
- allowed and blocked tools
- guards
- workflow flags
- policies
- recommended packages
- memory rules injected into the system prompt

The active project profile is stored at:

```text
.pi/harness-factory/active.json
```

### Manage harnesses

Provides project-local profile management:

- Duplicate harness
  - Copy a preset or existing harness into `.pi/harness-factory/profiles/`.
  - Useful before editing bundled presets.
- Edit project harness
  - Modify project-local mutation scope, validation strictness, safety gates, autonomy, and output style.
- Delete project harness
  - Deletes project-local profiles only.
  - Bundled presets cannot be deleted.
- Import / Export
  - Export a harness profile to JSON.
  - Import a harness JSON into the current project after validation and confirmation.

## Built-in presets

- `tdd` — strict coder profile with preset `Strict TDD — test-first, strict structure, full validation`, broad refactor scope, `Always` validation strictness, strict safety gates, and plan-then-act workflow.
- `safe-coder` — cautious everyday implementation mode with safety gates.
- `code-reviewer` — read-only review mode focused on actionable findings.
- `researcher` — evidence-first research mode with uncertainty handling.

## Harnessing axes

Generated and edited profiles are built from functional axes.

### Mutation scope

```text
Read-only
Artifacts only
Minimal edits
Focused refactors
Broad refactors
```

### Validation strictness

```text
Manual
After edits
Always
Test-first
Release-grade
```

### Safety gates

```text
Lightweight
Balanced
Strict
Read-only
Release-safe
```

### Autonomy

```text
Ask first
Plan then act
Act within scope
Autonomous
Review-gated
```

### Output style

```text
Concise summary
Detailed rationale
Findings table
Artifact-first
```

These choices compile into the profile fields Pi uses at runtime:

- `tools.allowed`
- `tools.blocked`
- `tools.readOnly`
- `guards`
- `workflow`
- `policies`
- `capabilities`
- `memory`

## Commands

```text
/factory
/factory help
/factory browse
/factory list
/factory pick <profile-id>
/factory create
/factory active
/factory preview <profile-id>
/factory use <profile-id>
/factory switch <profile-id>
/factory manage
```

## What the MVP enforces

- Blocks tools listed in the active profile's `tools.blocked`.
- Enforces read-only mode for `write` and `edit` when enabled.
- Asks before sensitive file access, such as `.env`, private keys, credentials, or secrets.
- Asks before dangerous shell commands, such as recursive delete, `sudo`, force push, or `chmod 777`.
- Asks before `git push` when the active profile requires it.
- Shows the active harness label in the Pi status area.
- Injects active harness instructions into the agent system prompt.
- Records recommended packages, allowed packages, and capability bindings in generated profiles.

## Safety model

This package is a Pi extension and prompt/tool-policy layer, not an OS sandbox. It is designed to make Pi sessions more consistent by combining generated instructions with extension hooks. It cannot control commands run outside Pi or tools that bypass Pi's extension hooks.

## Development

Run validation:

```bash
npm test
npm pack --dry-run
```

pi-harness-factory

Create, switch, and manage functional harness profiles for Pi Coding Agent.

Concept

pi-harness-factory turns Pi into a project-local harness factory. A harness is a compiled working mode: tool access, mutation scope, validation strictness, safety gates, workflow rules, UI label, memory hints, recommended Pi packages, and capabilities.

The goal is not just to pick a persona. The factory helps you answer:

What should the agent be allowed to do, how strict should it be, and what safety checks should apply for this project?

Install

Try from a local checkout without installing permanently:

pi -e ./

Install from GitHub:

pi install git:github.com/kswift1/pi-harness-factory

Install from npm:

pi install npm:pi-harness-factory

Quick start

Install the package, then restart Pi or run /reload in an existing Pi session so the /factory command is registered:

pi install npm:pi-harness-factory

Then run inside Pi:

/factory
/factory list
/factory use tdd

With the bundled tdd profile active, Pi receives a strict coder harness: broad refactor scope, Always validation strictness, Strict safety gates, and Plan then act autonomy. In practice it plans before edits, validates after edits, summarizes changes, and asks before secret access, dangerous commands, deletes, or git push.

Main menu

Run:

/factory

The factory opens a menu:

Use a harness
Create a harness
Current harness
Manage harnesses

Use a harness

Opens an interactive card browser. Cards summarize each harness by functional behavior:

mode / role
allowed tools
validation strictness
mutation scope
safety level
confirmations
workflow rules

You can also use direct commands:

/factory browse
/factory list
/factory pick <profile-id>
/factory use <profile-id>

Create a harness

Creates a project-local harness with a guided flow:

Choose role
- Coder
- Reviewer
- Researcher
- DevOps
- PM / Writer
- Custom
Choose role preset
- Safe implementation
- Strict TDD
- Read-only review
- Evidence researcher
- Release operator
Customize harnessing axes
- mutation scope
- validation strictness
- safety gates
- autonomy
- output style
Preview compiled rules
Save only or Save & Activate

Generated profiles are saved under:

.pi/harness-factory/profiles/<profile-id>.json

Current harness

Shows the active harness and the rules currently affecting Pi:

persona / role summary
allowed and blocked tools
guards
workflow flags
policies
recommended packages
memory rules injected into the system prompt

The active project profile is stored at:

.pi/harness-factory/active.json

Manage harnesses

Provides project-local profile management:

Duplicate harness
- Copy a preset or existing harness into .pi/harness-factory/profiles/.
- Useful before editing bundled presets.
Edit project harness
- Modify project-local mutation scope, validation strictness, safety gates, autonomy, and output style.
Delete project harness
- Deletes project-local profiles only.
- Bundled presets cannot be deleted.
Import / Export
- Export a harness profile to JSON.
- Import a harness JSON into the current project after validation and confirmation.

Built-in presets

tdd — strict coder profile with preset Strict TDD — test-first, strict structure, full validation, broad refactor scope, Always validation strictness, strict safety gates, and plan-then-act workflow.
safe-coder — cautious everyday implementation mode with safety gates.
code-reviewer — read-only review mode focused on actionable findings.
researcher — evidence-first research mode with uncertainty handling.

Harnessing axes

Generated and edited profiles are built from functional axes.

Mutation scope

Read-only
Artifacts only
Minimal edits
Focused refactors
Broad refactors

Validation strictness

Manual
After edits
Always
Test-first
Release-grade

Safety gates

Lightweight
Balanced
Strict
Read-only
Release-safe

Autonomy

Ask first
Plan then act
Act within scope
Autonomous
Review-gated

Output style

Concise summary
Detailed rationale
Findings table
Artifact-first

These choices compile into the profile fields Pi uses at runtime:

tools.allowed
tools.blocked
tools.readOnly
guards
workflow
policies
capabilities
memory

Commands

/factory
/factory help
/factory browse
/factory list
/factory pick <profile-id>
/factory create
/factory active
/factory preview <profile-id>
/factory use <profile-id>
/factory switch <profile-id>
/factory manage

What the MVP enforces

Blocks tools listed in the active profile's tools.blocked.
Enforces read-only mode for write and edit when enabled.
Asks before sensitive file access, such as .env, private keys, credentials, or secrets.
Asks before dangerous shell commands, such as recursive delete, sudo, force push, or chmod 777.
Asks before git push when the active profile requires it.
Shows the active harness label in the Pi status area.
Injects active harness instructions into the agent system prompt.
Records recommended packages, allowed packages, and capability bindings in generated profiles.

Safety model

This package is a Pi extension and prompt/tool-policy layer, not an OS sandbox. It is designed to make Pi sessions more consistent by combining generated instructions with extension hooks. It cannot control commands run outside Pi or tools that bypass Pi's extension hooks.

Development

Run validation:

npm test
npm pack --dry-run