lessons-pi

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

原始内容

# Lessons

**English** | [简体中文](https://github.com/lee259/lessons/blob/HEAD/README.zh-CN.md)

**Verified engineering lessons for coding agents** — not chat soft-memory.

After a real file change + passing test/build/lint/typecheck, Lessons captures a
distilled L2 Lesson as reviewable Markdown in your repo.

**Status:** early preview `0.1.1` on npm · OpenCode + Pi · MIT  
**Packages:** `@lessons/core` · `@lessons/opencode` · `@lessons/pi`  
**Requires:** Node `>=20` · OpenCode `>=1.18` · Pi coding-agent `0.81` (Pi path needs Node `>=22.19`)

[Install](#install) · [First 3 minutes](#first-3-minutes) · [Docs](#docs) · [Contributing](#contributing)

---

## Why Lessons

| Typical agent memory | Lessons |
| --- | --- |
| Remembers chat / preferences | Remembers **verified** engineering lessons |
| Soft write bar | File change + task-shaped verification + L2 Lesson |
| Often private DB | Git-reviewable Markdown under `docs/lessons/` |

```text
change → verify → distill Lesson → Markdown Memory → next task reads it
```

## Install

Lessons ships two host adapters on the same Markdown core. OpenCode is the
primary dogfood path (one-command installer + host smoke). Pi shares compose /
seed / Quiet Capture through `@lessons/pi`.

### OpenCode

```bash
npx -y -p @lessons/opencode lessons-opencode install
```

Restart OpenCode, then run `/lessons-status`.

<details>
<summary>What the OpenCode installer does</summary>

1. Adds `"plugin": ["@lessons/opencode"]` to `~/.config/opencode/opencode.json(c)`
2. Writes `/lessons-seed` and `/lessons-status` under `~/.config/opencode/commands/`
3. Writes `~/.config/opencode/plugins/lessons.js` shim for local symlink installs
4. With `--local`, symlinks built packages into OpenCode `node_modules/@lessons/`

</details>

### Pi

```bash
pi install npm:@lessons/pi
```

Restart Pi (or `/reload`), then run `/lessons-status`. Details:
[`packages/pi/README.md`](https://github.com/lee259/lessons/blob/HEAD/packages/pi/README.md).

### Local monorepo (contributors)

```bash
git clone https://github.com/lee259/lessons.git
cd lessons
pnpm install && pnpm build
node packages/opencode/dist/cli.js install --local   # OpenCode
pi install ./packages/pi                             # Pi
```

## First 3 minutes

1. `/init` → project `AGENTS.md` (OpenCode native; **not** Lessons; skip on Pi)
2. `/lessons-seed` → narrative `docs/lessons/CONTEXT.md` ([ADR-003](https://github.com/lee259/lessons/blob/HEAD/docs/lessons/adr/003-context-seed-ownership.md))
3. After a verified task, Agent calls `lessons_finish_episode` with a short reusable summary

`/lessons-seed` ≠ `/init`. Soft-close does **not** Capture template summaries.

- OpenCode tools + prompts: [OpenCode usage](https://github.com/lee259/lessons/blob/HEAD/docs/en/opencode-usage.md)
- Pi surfaces: [`packages/pi/README.md`](https://github.com/lee259/lessons/blob/HEAD/packages/pi/README.md)

## What gets captured

Needs **all** of:

- concrete project file change
- task-shaped verification (`test` / `build` / `lint` / `typecheck` / …)
- reusable L2 Lesson (not “updated file X”, not raw tool stdout)

`pwd` / `ls` / `git status` never Capture. Chat-only claims never Capture.

## Preview scope

| In | Out |
| --- | --- |
| OpenCode plugin + Pi extension + Markdown Memories | Broader multi-host platform |
| Shared core compose / seed / Capture | Pi one-command install + host-smoke parity |
| Lesson-first Capture + CONTEXT seed | In-repo code-graph engine |
| Soft-fail host isolation | Production support / LTS guarantees |

## Docs

| Doc | Purpose |
| --- | --- |
| [docs/en/design-overview.md](https://github.com/lee259/lessons/blob/HEAD/docs/en/design-overview.md) | Short product overview |
| [docs/en/opencode-usage.md](https://github.com/lee259/lessons/blob/HEAD/docs/en/opencode-usage.md) | Tools + end-to-end OpenCode flows |
| [packages/pi/README.md](https://github.com/lee259/lessons/blob/HEAD/packages/pi/README.md) | Pi extension install + surfaces |
| [docs/lessons/adr/](https://github.com/lee259/lessons/tree/HEAD/docs/lessons/adr/) | Binding architecture decisions |
| [CONTRIBUTING.md](https://github.com/lee259/lessons/blob/HEAD/CONTRIBUTING.md) | Dev setup + PR checks |
| [SECURITY.md](https://github.com/lee259/lessons/blob/HEAD/SECURITY.md) | Reporting + redaction notes |
| [CHANGELOG.md](https://github.com/lee259/lessons/blob/HEAD/CHANGELOG.md) | Release notes |
| [README.zh-CN.md](https://github.com/lee259/lessons/blob/HEAD/README.zh-CN.md) | Chinese homepage |

## Contributing

```bash
pnpm install && pnpm verify
```

Optional OpenCode host checks (`OPENCODE_BIN` required): see [CONTRIBUTING.md](https://github.com/lee259/lessons/blob/HEAD/CONTRIBUTING.md).

## License

MIT — [LICENSE](https://github.com/lee259/lessons/tree/HEAD/LICENSE).

Lessons

English | 简体中文

Verified engineering lessons for coding agents — not chat soft-memory.

After a real file change + passing test/build/lint/typecheck, Lessons captures a distilled L2 Lesson as reviewable Markdown in your repo.

Status: early preview 0.1.1 on npm · OpenCode + Pi · MIT
Packages: @lessons/core · @lessons/opencode · @lessons/pi
Requires: Node >=20 · OpenCode >=1.18 · Pi coding-agent 0.81 (Pi path needs Node >=22.19)

Install · First 3 minutes · Docs · Contributing

Why Lessons

Typical agent memory	Lessons
Remembers chat / preferences	Remembers verified engineering lessons
Soft write bar	File change + task-shaped verification + L2 Lesson
Often private DB	Git-reviewable Markdown under `docs/lessons/`

change → verify → distill Lesson → Markdown Memory → next task reads it

Install

Lessons ships two host adapters on the same Markdown core. OpenCode is the primary dogfood path (one-command installer + host smoke). Pi shares compose / seed / Quiet Capture through @lessons/pi.

OpenCode

npx -y -p @lessons/opencode lessons-opencode install

Restart OpenCode, then run /lessons-status.

What the OpenCode installer does

Adds "plugin": ["@lessons/opencode"] to ~/.config/opencode/opencode.json(c)
Writes /lessons-seed and /lessons-status under ~/.config/opencode/commands/
Writes ~/.config/opencode/plugins/lessons.js shim for local symlink installs
With --local, symlinks built packages into OpenCode node_modules/@lessons/

Pi

pi install npm:@lessons/pi

Restart Pi (or /reload), then run /lessons-status. Details: packages/pi/README.md.

Local monorepo (contributors)

git clone https://github.com/lee259/lessons.git
cd lessons
pnpm install && pnpm build
node packages/opencode/dist/cli.js install --local   # OpenCode
pi install ./packages/pi                             # Pi

First 3 minutes

/init → project AGENTS.md (OpenCode native; not Lessons; skip on Pi)
/lessons-seed → narrative docs/lessons/CONTEXT.md (ADR-003)
After a verified task, Agent calls lessons_finish_episode with a short reusable summary

/lessons-seed ≠ /init. Soft-close does not Capture template summaries.

OpenCode tools + prompts: OpenCode usage
Pi surfaces: packages/pi/README.md

What gets captured

Needs all of:

concrete project file change
task-shaped verification (test / build / lint / typecheck / …)
reusable L2 Lesson (not “updated file X”, not raw tool stdout)

pwd / ls / git status never Capture. Chat-only claims never Capture.

Preview scope

In	Out
OpenCode plugin + Pi extension + Markdown Memories	Broader multi-host platform
Shared core compose / seed / Capture	Pi one-command install + host-smoke parity
Lesson-first Capture + CONTEXT seed	In-repo code-graph engine
Soft-fail host isolation	Production support / LTS guarantees

Docs

Doc	Purpose
docs/en/design-overview.md	Short product overview
docs/en/opencode-usage.md	Tools + end-to-end OpenCode flows
packages/pi/README.md	Pi extension install + surfaces
docs/lessons/adr/	Binding architecture decisions
CONTRIBUTING.md	Dev setup + PR checks
SECURITY.md	Reporting + redaction notes
CHANGELOG.md	Release notes
README.zh-CN.md	Chinese homepage

Contributing

pnpm install && pnpm verify

Optional OpenCode host checks (OPENCODE_BIN required): see CONTRIBUTING.md.

License

MIT — LICENSE.