pi-kage 0.3.7 → 0.3.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.
- package/README.md +69 -145
- package/README.zh-CN.md +121 -0
- package/bin/kage.mjs +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,115 +4,73 @@
|
|
|
4
4
|
[](https://www.npmjs.com/package/pi-kage)
|
|
5
5
|
[](./LICENSE)
|
|
6
6
|
|
|
7
|
-
>
|
|
7
|
+
> 影分身の術 — Shadow Clone Jutsu for your git repo. · [中文](./README.zh-CN.md)
|
|
8
8
|
|
|
9
9
|
<p align="center"><img src="./assets/demo.svg" alt="kage demo" width="100%"></p>
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
Instead of a shared [`git worktree`](https://git-scm.com/docs/git-worktree), kage gives each session
|
|
16
|
-
its own **full copy** of the repo in a sibling folder — its own working tree, its own `.git`. Code
|
|
17
|
-
comes back through git (a PR, or a branch fetch); the agent's session memory comes back through
|
|
18
|
-
`~/.pi`. kage never copies a working tree back onto the origin, so concurrent sessions can't collide.
|
|
19
|
-
And like a real Naruto shadow clone, the clone carries the agent's memory out and returns it on
|
|
20
|
-
dispel (see [How it works](#how-it-works)).
|
|
11
|
+
Run several AI coding-agent sessions on one repo at the same time. Point two agents at the same
|
|
12
|
+
checkout and they fight over one working tree — same files, same branches, each other's uncommitted
|
|
13
|
+
changes. kage gives each session its **own full copy** of the repo in a sibling folder, so they
|
|
14
|
+
can't collide.
|
|
21
15
|
|
|
22
16
|
```bash
|
|
23
17
|
npm install -g pi-kage
|
|
24
18
|
cd my-app
|
|
25
|
-
kage
|
|
26
|
-
# ...
|
|
27
|
-
kage finish
|
|
19
|
+
kage # 🥷 copy → ../my-app--kage-<ts>, open a fresh pi
|
|
20
|
+
# ...commit, push, open a PR, quit pi...
|
|
21
|
+
kage finish # 💨 merge the clone's sessions back, delete the clone
|
|
28
22
|
```
|
|
29
23
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
## Why a full copy instead of `git worktree`?
|
|
24
|
+
Code comes back through git (a PR, or a branch fetch). The agent's session memory comes back through
|
|
25
|
+
`~/.pi`. kage never copies a working tree back onto the origin — that's the whole point.
|
|
33
26
|
|
|
34
|
-
|
|
35
|
-
repo's single `.git`. For parallel agents that shared `.git` is the problem:
|
|
27
|
+
## Why a full copy, not `git worktree`?
|
|
36
28
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
29
|
+
A [`git worktree`](https://git-scm.com/docs/git-worktree) gives you a second working directory, but
|
|
30
|
+
every worktree shares one `.git` — so two agents can't check out the same branch, and stash/refs/index
|
|
31
|
+
are shared. A worktree is also a clean checkout: no `node_modules`, `.env`, build cache, so each one
|
|
32
|
+
needs a setup pass first.
|
|
41
33
|
|
|
42
|
-
A full copy has
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
34
|
+
A full copy has independent `.git`, independent branches, and every gitignored/untracked file already
|
|
35
|
+
in place. The cost is disk and copy time — which on APFS (macOS) and reflink filesystems (Linux) kage
|
|
36
|
+
sidesteps with a copy-on-write clone: near-instant, no extra space until files actually change. Other
|
|
37
|
+
filesystems fall back to a plain recursive copy.
|
|
46
38
|
|
|
47
39
|
## Install
|
|
48
40
|
|
|
49
41
|
```bash
|
|
50
|
-
#
|
|
51
|
-
|
|
52
|
-
npx pi-kage # or run without installing
|
|
42
|
+
npm install -g pi-kage # or: pnpm add -g pi-kage
|
|
43
|
+
npx pi-kage # run without installing
|
|
53
44
|
|
|
54
|
-
#
|
|
55
|
-
pnpm add -g pi-kage
|
|
56
|
-
pnpm dlx pi-kage # or run without installing
|
|
57
|
-
|
|
58
|
-
# or install script (no npm needed — kage is a single, zero-dependency Node script)
|
|
45
|
+
# install script (single zero-dependency Node script → ~/.local/bin)
|
|
59
46
|
curl -fsSL https://raw.githubusercontent.com/kid7st/kage/main/install.sh | sh
|
|
60
47
|
```
|
|
61
48
|
|
|
62
|
-
|
|
63
|
-
|
|
49
|
+
Requires **git**, [**pi**](https://github.com/earendil-works), and **Node ≥ 18** on your `PATH`.
|
|
50
|
+
kage has no runtime dependencies.
|
|
64
51
|
|
|
65
52
|
From source:
|
|
66
53
|
|
|
67
54
|
```bash
|
|
68
55
|
git clone https://github.com/kid7st/kage
|
|
69
|
-
cd kage && npm install && npm link #
|
|
56
|
+
cd kage && npm install && npm link # npm install builds bin/kage.mjs from src/
|
|
70
57
|
```
|
|
71
58
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
## Lifecycle
|
|
59
|
+
## Commands
|
|
75
60
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
· safety check (committed? pushed?)
|
|
86
|
-
· merge the clone's new sessions into ~/.pi
|
|
87
|
-
· delete the clone folder
|
|
88
|
-
code arrives via the merged GitHub PR ✓
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
## Usage
|
|
92
|
-
|
|
93
|
-
```bash
|
|
94
|
-
cd ~/code/my-app
|
|
95
|
-
|
|
96
|
-
kage # clone . → ../my-app--kage-<ts>, open a fresh pi (origin history resumable)
|
|
97
|
-
kage --name fix-login # name the clone folder: ../my-app--fix-login
|
|
98
|
-
kage /path/to/other-repo # clone a different repo (path defaults to cwd)
|
|
99
|
-
|
|
100
|
-
# back in the origin after you quit the clone's pi:
|
|
101
|
-
kage # no args inside a repo with clones -> interactive menu
|
|
102
|
-
kage status # status dashboard: branch · dirty · ahead/behind · safe-to-clean
|
|
103
|
-
kage status --pr # also show PR state (via gh)
|
|
104
|
-
kage finish fix-login # check → merge the clone's new sessions back → delete the clone
|
|
105
|
-
kage finish fix-login --pr # push the branch + open a PR (via gh), then finish
|
|
106
|
-
kage finish --force # skip the uncommitted/unpushed guard
|
|
107
|
-
kage rm old-experiment # discard a clone without merging (refuses if it has local-only work)
|
|
108
|
-
|
|
109
|
-
# inside a clone, to retrieve a non-git file (e.g. a generated .env):
|
|
110
|
-
kage pull .env config/local.json
|
|
111
|
-
```
|
|
61
|
+
| Command | Run from | What it does |
|
|
62
|
+
|---|---|---|
|
|
63
|
+
| `kage [path] [--name x]` | origin repo | Copy the repo to `../<repo>--<name>` (default `kage-<ts>`), copy in the origin's 5 most recent pi sessions (resumable, never replayed), and launch a **fresh** pi. `--name` only names the folder — kage never creates a branch. No args + existing clones → interactive menu. |
|
|
64
|
+
| `kage status [--pr]` | origin repo | Dashboard: branch, dirty/clean, ahead/behind, "safe to clean". `--pr` adds PR state via `gh`. (`kage list` is an alias.) |
|
|
65
|
+
| `kage finish [name] [--force] [--push] [--pr]` | origin / inside clone | Refuse if the clone has uncommitted or unpushed work, merge its **new** sessions back, delete it. `--push` pushes the branch first; `--pr` pushes + opens a PR via `gh`; `--force` skips the guard. |
|
|
66
|
+
| `kage rm [name] [--force]` | origin / inside clone | Discard a clone **without** merging memory. Refuses local-only work unless `--force`. |
|
|
67
|
+
| `kage pull <path...>` | inside a clone | Copy specific files/dirs (even gitignored, e.g. a generated `.env`) back to the origin. |
|
|
68
|
+
| `kage shell-init` | shell rc | Shell wrapper (cd back to origin after `finish`/`rm`) + tab completion. Use `eval "$(kage shell-init)"`. |
|
|
69
|
+
| `kage --help` / `--version` | anywhere | Usage / version. |
|
|
112
70
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
71
|
+
Run bare `kage` inside a repo that already has clones to get an interactive picker: create a new clone,
|
|
72
|
+
or **enter** / **finish** / **remove** an existing one. `finish` and `rm` show the same picker when you
|
|
73
|
+
have several clones and don't name one.
|
|
116
74
|
|
|
117
75
|
### Shell integration (optional)
|
|
118
76
|
|
|
@@ -120,84 +78,50 @@ show the same picker when you have multiple clones and don't name one.
|
|
|
120
78
|
eval "$(kage shell-init)" # add to ~/.zshrc or ~/.bashrc
|
|
121
79
|
```
|
|
122
80
|
|
|
123
|
-
|
|
124
|
-
automatically (a CLI can't change its parent shell
|
|
125
|
-
for subcommands and clone names.
|
|
126
|
-
|
|
127
|
-
### Commands
|
|
128
|
-
|
|
129
|
-
| Command | Run from | What it does |
|
|
130
|
-
|---|---|---|
|
|
131
|
-
| `kage [path] [--name x]` | origin repo | Copy the repo to `../<repo>--<name>` (default `kage-<ts>`), copy the origin's 5 most recent pi sessions into the clone (resumable there, never replayed), and launch a **fresh** `pi` session. `--name` only names the folder — kage never creates a branch. With no args (and existing clones) it opens an interactive picker. |
|
|
132
|
-
| `kage status [--pr]` | origin repo | Status dashboard of clones: branch, dirty/clean, ahead/behind upstream, and a “safe to clean” flag. `--pr` adds PR state via `gh`. (`kage list` is a kept alias.) |
|
|
133
|
-
| `kage finish [name] [--force] [--push] [--pr]` | origin, inside the clone, or anywhere with a clone path | Refuse if the clone has uncommitted or unpushed work (`--force` overrides), merge the clone's **new** sessions back (copied-in origin history is skipped), then delete the clone. `--push` pushes the branch first; `--pr` pushes and opens a PR via `gh`. Auto-selects / prompts when there are several. |
|
|
134
|
-
| `kage rm [name] [--force]` | origin, inside the clone, or anywhere with a clone path | Discard a clone **without** merging memory. Refuses if it has local-only work unless `--force`. For abandoned experiments. `name` may be a clone name (run from the repo) or a path to the clone folder (works from anywhere). |
|
|
135
|
-
| `kage pull <path...>` | inside a clone | Copy specific files/dirs (even gitignored ones) back to the origin at the same relative path. |
|
|
136
|
-
| `kage shell-init` | shell rc | Print a shell wrapper (cd-back after `finish`/`rm`) + tab completion. Use `eval "$(kage shell-init)"`. |
|
|
137
|
-
| `kage --help` / `--version` | anywhere | Usage / version. |
|
|
81
|
+
Running `finish`/`rm` from inside a clone deletes the directory your shell is sitting in. The wrapper
|
|
82
|
+
cd's you back to the origin automatically (a CLI can't change its parent shell otherwise) and adds tab
|
|
83
|
+
completion for subcommands and clone names.
|
|
138
84
|
|
|
139
85
|
## How it works
|
|
140
86
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
4. **The origin is read-only to kage** — it only copies out and writes session memory; it never
|
|
160
|
-
touches the origin's working tree, even while another session is live there.
|
|
161
|
-
|
|
162
|
-
With a remote configured, `finish` nudges you to push first (so PR-flow mistakes surface) unless you
|
|
163
|
-
pass `--push` / `--pr` / `--force`.
|
|
164
|
-
|
|
165
|
-
## Notes & caveats
|
|
166
|
-
|
|
167
|
-
- The copy is a snapshot of the origin's **current** state, **including uncommitted changes**.
|
|
168
|
-
- **Submodules**: a submodule's `.git` pointer is an absolute path and breaks on copy — run
|
|
87
|
+
- **Isolation.** A clone is a full independent copy with its own `.git`. kage does **not** create a
|
|
88
|
+
branch — the clone stays on the origin's current branch and stays out of git flow, so you own the
|
|
89
|
+
branching/PR workflow inside the clone (tell the agent via your `AGENTS.md`).
|
|
90
|
+
- **Code flows back via git, never the working tree.** With a remote: push the branch, merge the PR.
|
|
91
|
+
Without a remote: `finish` fetches the clone's branch into the origin's git as a local
|
|
92
|
+
`kage/<name>-<sha>` branch (origin working tree untouched — `git merge` it when you like). Because a
|
|
93
|
+
fetch can't preserve uncommitted work, `finish` refuses to delete a dirty clone unless `--force`.
|
|
94
|
+
- **Memory flows via `~/.pi`, never replayed.** On create, the origin's 5 most recent sessions are
|
|
95
|
+
copied in — pi's resume picker surfaces them, but the clone opens a **fresh** session. On `finish`,
|
|
96
|
+
sessions the clone created come back whole; a copied-in session you resumed comes back as a separate
|
|
97
|
+
new session, so the origin's original is never mutated.
|
|
98
|
+
- **The origin is read-only to kage.** It only copies out and writes session memory — it never touches
|
|
99
|
+
the origin's working tree, even while another session is live there.
|
|
100
|
+
|
|
101
|
+
## Notes
|
|
102
|
+
|
|
103
|
+
- The copy snapshots the origin's **current** state, including uncommitted changes.
|
|
104
|
+
- **Submodules**: a submodule's `.git` is an absolute path and breaks on copy — run
|
|
169
105
|
`git submodule update --init` in the clone.
|
|
170
|
-
-
|
|
171
|
-
- Session storage is assumed at `~/.pi/agent/sessions`; override with `KAGE_SESSIONS_DIR`.
|
|
106
|
+
- Session storage defaults to `~/.pi/agent/sessions`; override with `KAGE_SESSIONS_DIR`.
|
|
172
107
|
|
|
173
108
|
## Development
|
|
174
109
|
|
|
175
|
-
The CLI
|
|
176
|
-
|
|
177
|
-
- `src/kage.mts` → `bin/kage.mjs` — a single, zero-runtime-dependency file (the only thing the
|
|
178
|
-
install script + npm package ship).
|
|
179
|
-
- `test/kage.test.mts` → `dist/kage.test.mjs` — black-box `node:test` smoke tests that spawn the
|
|
180
|
-
built CLI (compiled to `dist/` so they run on every Node in CI, no TS loader needed).
|
|
181
|
-
|
|
182
|
-
`bin/` and `dist/` are build artifacts — both gitignored. `bin/` is produced on `npm install`
|
|
183
|
-
(via `prepare`), so `npm link` from a clone just works.
|
|
110
|
+
The CLI is TypeScript compiled to a single zero-dependency file:
|
|
184
111
|
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
```bash
|
|
189
|
-
npm run build # tsc: src/kage.mts -> bin/kage.mjs
|
|
190
|
-
npm run format # biome: auto-format + safe lint fixes
|
|
191
|
-
npm run lint # biome (lint + format check) + tsc type check (src + test)
|
|
192
|
-
npm test # build CLI + tests, then run node:test smoke tests (temp repos, no network)
|
|
193
|
-
```
|
|
112
|
+
- `src/kage.mts` → `bin/kage.mjs` (the only thing shipped)
|
|
113
|
+
- `test/kage.test.mts` → `dist/` — black-box `node:test` smoke tests that spawn the built CLI
|
|
194
114
|
|
|
195
|
-
|
|
115
|
+
`bin/` and `dist/` are gitignored build artifacts; `bin/` is produced on `npm install` (via `prepare`),
|
|
116
|
+
so `npm link` from a clone just works. Linting/formatting is [Biome](https://biomejs.dev) (dev-only).
|
|
196
117
|
|
|
197
118
|
```bash
|
|
198
|
-
|
|
119
|
+
npm run build # tsc: src/kage.mts → bin/kage.mjs
|
|
120
|
+
npm run lint # biome + tsc type check
|
|
121
|
+
npm test # build + node:test smoke tests (temp repos, no network)
|
|
199
122
|
```
|
|
200
123
|
|
|
124
|
+
Releases: bump `version` in `package.json`, then `git tag vX.Y.Z && git push origin main vX.Y.Z`.
|
|
201
125
|
CI runs lint + tests and `npm publish --provenance` on any `v*` tag.
|
|
202
126
|
|
|
203
127
|
## License
|
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
# kage 🥷
|
|
2
|
+
|
|
3
|
+
[](https://github.com/kid7st/kage/actions/workflows/ci.yml)
|
|
4
|
+
[](https://www.npmjs.com/package/pi-kage)
|
|
5
|
+
[](./LICENSE)
|
|
6
|
+
|
|
7
|
+
> 影分身の術 —— 给你的 git 仓库来一发影分身。· [English](./README.md)
|
|
8
|
+
|
|
9
|
+
<p align="center"><img src="./assets/demo.svg" alt="kage demo" width="100%"></p>
|
|
10
|
+
|
|
11
|
+
在同一个仓库上同时跑多个 AI coding agent。让两个 agent 指向同一个 checkout，它们就会抢同一个工作区
|
|
12
|
+
——改同样的文件、撞同样的分支、踩到彼此未提交的改动。kage 给每个 session 一份**独立的完整副本**，放在
|
|
13
|
+
同级目录里，从根本上避免冲突。
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm install -g pi-kage
|
|
17
|
+
cd my-app
|
|
18
|
+
kage # 🥷 复制 → ../my-app--kage-<ts>，打开一个全新的 pi
|
|
19
|
+
# ...提交、push、开 PR、退出 pi...
|
|
20
|
+
kage finish # 💨 把分身的 session 合并回来，删掉分身
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
代码通过 git 回流（一个 PR，或者 fetch 分支）；agent 的 session 记忆通过 `~/.pi` 回流。kage 从不把工作区
|
|
24
|
+
复制回原仓库 —— 这正是它存在的意义。
|
|
25
|
+
|
|
26
|
+
## 为什么用完整副本，而不是 `git worktree`？
|
|
27
|
+
|
|
28
|
+
[`git worktree`](https://git-scm.com/docs/git-worktree) 能给你第二个工作目录，但所有 worktree 共享同一个
|
|
29
|
+
`.git`：两个 agent 没法 checkout 同一个分支，stash / refs / index 也都是共享的。而且 worktree 是干净的
|
|
30
|
+
checkout —— 没有 `node_modules`、`.env`、build 缓存，每个都得先跑一遍环境初始化。
|
|
31
|
+
|
|
32
|
+
完整副本则有独立的 `.git`、独立的分支，所有被 gitignore 或未跟踪的文件也都已就位。代价是磁盘和复制时间
|
|
33
|
+
—— 而在 APFS（macOS）和支持 reflink 的文件系统（Linux）上，kage 用写时复制（copy-on-write）绕开了这个代价：
|
|
34
|
+
几乎瞬间完成，文件真正发生改动前不占额外空间。其它文件系统则退化为普通的递归复制。
|
|
35
|
+
|
|
36
|
+
## 安装
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
npm install -g pi-kage # 或：pnpm add -g pi-kage
|
|
40
|
+
npx pi-kage # 不安装直接运行
|
|
41
|
+
|
|
42
|
+
# 安装脚本（单个零依赖的 Node 脚本 → ~/.local/bin）
|
|
43
|
+
curl -fsSL https://raw.githubusercontent.com/kid7st/kage/main/install.sh | sh
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
需要 `PATH` 上有 **git**、[**pi**](https://github.com/earendil-works) 和 **Node ≥ 18**。
|
|
47
|
+
kage 没有任何运行时依赖。
|
|
48
|
+
|
|
49
|
+
从源码安装：
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
git clone https://github.com/kid7st/kage
|
|
53
|
+
cd kage && npm install && npm link # npm install 会从 src/ 编译出 bin/kage.mjs
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## 命令
|
|
57
|
+
|
|
58
|
+
| 命令 | 在哪运行 | 作用 |
|
|
59
|
+
|---|---|---|
|
|
60
|
+
| `kage [path] [--name x]` | 原仓库 | 把仓库复制到 `../<repo>--<name>`（默认 `kage-<ts>`），拷入原仓库最近 5 个 pi session（可 resume，绝不重放），并启动一个**全新**的 pi。`--name` 只命名文件夹 —— kage 从不建分支。无参数 + 已有分身 → 进入交互菜单。 |
|
|
61
|
+
| `kage status [--pr]` | 原仓库 | 仪表盘：分支、是否有改动、ahead/behind、是否「可安全清理」。`--pr` 通过 `gh` 附带 PR 状态。（`kage list` 是别名。） |
|
|
62
|
+
| `kage finish [name] [--force] [--push] [--pr]` | 原仓库 / 分身内 | 若分身有未提交或未 push 的改动则拒绝，把它**新产生**的 session 合并回来，再删除它。`--push` 先 push 分支；`--pr` push 并通过 `gh` 开 PR；`--force` 跳过检查。 |
|
|
63
|
+
| `kage rm [name] [--force]` | 原仓库 / 分身内 | **不**合并记忆地丢弃一个分身。若有仅存在于本地的工作则拒绝，除非加 `--force`。 |
|
|
64
|
+
| `kage pull <path...>` | 分身内 | 把指定文件/目录（包括被 gitignore 的，比如生成的 `.env`）按相同相对路径拷回原仓库。 |
|
|
65
|
+
| `kage shell-init` | shell 配置 | shell 包装函数（`finish`/`rm` 后自动 cd 回原仓库）+ tab 补全。用 `eval "$(kage shell-init)"`。 |
|
|
66
|
+
| `kage --help` / `--version` | 任意位置 | 用法 / 版本。 |
|
|
67
|
+
|
|
68
|
+
在已有分身的仓库里直接运行 `kage`，会弹出交互选择器：新建一个分身，或对已有分身执行 **进入** / **finish** /
|
|
69
|
+
**删除**。当有多个分身又没指定名字时，`finish` 和 `rm` 也会弹出同样的选择器。
|
|
70
|
+
|
|
71
|
+
### Shell 集成（可选）
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
eval "$(kage shell-init)" # 加到 ~/.zshrc 或 ~/.bashrc
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
在分身内运行 `finish`/`rm` 会删掉你 shell 当前所在的目录。这个包装函数会自动把你 cd 回原仓库（否则 CLI
|
|
78
|
+
没法改变父 shell 的目录），并为子命令和分身名加上 tab 补全。
|
|
79
|
+
|
|
80
|
+
## 工作原理
|
|
81
|
+
|
|
82
|
+
- **隔离。** 一个分身是带独立 `.git` 的完整副本。kage **不**建分支 —— 分身停在原仓库当前分支上，且完全不
|
|
83
|
+
介入 git 流程，所以分身内的分支 / PR 工作流由你自己决定（通过 `AGENTS.md` 告诉 agent）。
|
|
84
|
+
- **代码只经由 git 回流，绝不经过工作区。** 有 remote 时：push 分支、合并 PR。没有 remote 时：`finish` 会把
|
|
85
|
+
分身的分支 fetch 进原仓库的 git，存成本地分支 `kage/<name>-<sha>`（原仓库工作区不动 —— 你想合并时再
|
|
86
|
+
`git merge`）。由于 fetch 无法保留未提交的改动，`finish` 拒绝删除有改动的分身，除非加 `--force`。
|
|
87
|
+
- **记忆只经由 `~/.pi` 回流，绝不重放。** 创建时拷入原仓库最近 5 个 session —— pi 的 resume 选择器能看到它们，
|
|
88
|
+
但分身本身打开的是**全新** session。`finish` 时，分身自己产生的 session 整份拷回；你 resume 过的拷入 session
|
|
89
|
+
会作为一个独立的新 session 回来，原仓库的原始 session 绝不被改动。
|
|
90
|
+
- **对 kage 而言原仓库是只读的。** 它只往外复制、只写 session 记忆 —— 即使原仓库里另有一个 session 正活跃，
|
|
91
|
+
它也绝不碰原仓库的工作区。
|
|
92
|
+
|
|
93
|
+
## 注意事项
|
|
94
|
+
|
|
95
|
+
- 副本是原仓库**当前**状态的快照，包含未提交的改动。
|
|
96
|
+
- **Submodule**：submodule 的 `.git` 是绝对路径，复制后会失效 —— 在分身里跑一次
|
|
97
|
+
`git submodule update --init`。
|
|
98
|
+
- Session 存储默认在 `~/.pi/agent/sessions`，可用 `KAGE_SESSIONS_DIR` 覆盖。
|
|
99
|
+
|
|
100
|
+
## 开发
|
|
101
|
+
|
|
102
|
+
CLI 用 TypeScript 写，编译成单个零依赖文件：
|
|
103
|
+
|
|
104
|
+
- `src/kage.mts` → `bin/kage.mjs`（唯一发布的文件）
|
|
105
|
+
- `test/kage.test.mts` → `dist/` —— 启动编译后 CLI 的黑盒 `node:test` 冒烟测试
|
|
106
|
+
|
|
107
|
+
`bin/` 和 `dist/` 是被 gitignore 的构建产物；`bin/` 在 `npm install` 时（通过 `prepare`）生成，所以从克隆出来
|
|
108
|
+
的仓库直接 `npm link` 即可。代码检查 / 格式化用 [Biome](https://biomejs.dev)（仅开发依赖）。
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
npm run build # tsc: src/kage.mts → bin/kage.mjs
|
|
112
|
+
npm run lint # biome + tsc 类型检查
|
|
113
|
+
npm test # 构建 + node:test 冒烟测试（临时仓库，不联网）
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
发布：在 `package.json` 里更新 `version`，然后 `git tag vX.Y.Z && git push origin main vX.Y.Z`。
|
|
117
|
+
任何 `v*` tag 都会触发 CI 跑 lint + 测试并执行 `npm publish --provenance`。
|
|
118
|
+
|
|
119
|
+
## License
|
|
120
|
+
|
|
121
|
+
[MIT](./LICENSE)
|
package/bin/kage.mjs
CHANGED
|
@@ -28,7 +28,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, wri
|
|
|
28
28
|
import { homedir } from "node:os";
|
|
29
29
|
import { basename, dirname, join, resolve, sep } from "node:path";
|
|
30
30
|
import readline from "node:readline";
|
|
31
|
-
const VERSION = "0.3.
|
|
31
|
+
const VERSION = "0.3.8"; // keep in sync with package.json (enforced by test)
|
|
32
32
|
const MARKER = ".kage.json";
|
|
33
33
|
const SESSIONS = process.env.KAGE_SESSIONS_DIR || join(homedir(), ".pi", "agent", "sessions");
|
|
34
34
|
const RECENT_SESSIONS = 5; // how many of the origin's most-recent sessions to copy into a clone
|
package/package.json
CHANGED