@zythegit/agentforge 0.1.2 → 0.2.0
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 +36 -141
- package/dist/aforge.js +403 -358
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -11,74 +11,22 @@
|
|
|
11
11
|
- **learnings/**：从实战经验沉淀、待确认的条目（`aforge learn`）；
|
|
12
12
|
- **templates/、skills/、mcp/**：可复用模板、技能与 MCP 服务器声明。
|
|
13
13
|
|
|
14
|
-
执行 `aforge sync` 后，以上内容被渲染并写入各 Agent 的原生规则文件。AgentForge 只管理文件中的 marker
|
|
14
|
+
执行 `aforge sync` 后，以上内容被渲染并写入各 Agent 的原生规则文件。AgentForge 只管理文件中的 marker 区间，区间外你的手写内容原样保留。规则正文之外，同一次 `sync` 还会投影技能目录、MCP 配置，以及（按需开启的）命令薄壳。
|
|
15
15
|
|
|
16
16
|
## 安装
|
|
17
17
|
|
|
18
|
-
### 方式一：npx 直接用（推荐，无需克隆）
|
|
19
|
-
|
|
20
18
|
前置：Node ≥ 20.19。
|
|
21
19
|
|
|
22
20
|
```powershell
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
npx -y @zythegit/agentforge@latest init -i
|
|
26
|
-
|
|
27
|
-
# 常用则全局装，之后直接 aforge
|
|
28
|
-
npm i -g @zythegit/agentforge
|
|
29
|
-
aforge --version
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
包名是 `@zythegit/agentforge`，命令名是 `aforge`。发布产物是 esbuild 打出的单文件 bundle（依赖已内联），因此 `npx` 冷启动只下载一个文件，不再安装任何运行时依赖。
|
|
33
|
-
|
|
34
|
-
### 方式二：下载独立二进制（免 Node，兜底）
|
|
35
|
-
|
|
36
|
-
只有在目标机器装不了 Node 时才需要这条路：二进制内嵌了 bun 运行时，压缩包 36~39 MB（解包后 64~86 MB），比 npm 包大两个数量级。
|
|
37
|
-
|
|
38
|
-
从 [Releases](https://github.com/zyTheGit/AgentForge/releases) 下载对应平台的压缩包（附 `checksums.txt`，内容是**压缩包**的 sha256）：
|
|
39
|
-
|
|
40
|
-
| 平台 | 资产 |
|
|
41
|
-
| --- | --- |
|
|
42
|
-
| Windows x64 | `aforge-win32-x64.zip` |
|
|
43
|
-
| Linux x64 / arm64 | `aforge-linux-x64.tar.gz` / `aforge-linux-arm64.tar.gz` |
|
|
44
|
-
| macOS Apple Silicon / Intel | `aforge-darwin-arm64.tar.gz` / `aforge-darwin-x64.tar.gz` |
|
|
45
|
-
|
|
46
|
-
解包后重命名为 `aforge`（Windows 为 `aforge.exe`）放进 PATH 即可。
|
|
47
|
-
|
|
48
|
-
macOS 上二进制未做签名与公证，首次运行会被 Gatekeeper 拦下，需手动去掉隔离属性：
|
|
49
|
-
|
|
50
|
-
```bash
|
|
51
|
-
xattr -d com.apple.quarantine ./aforge
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
`aforge-linux-arm64` 在 CI 里只靠 QEMU 模拟跑过 `--version`，没有 arm64 真机验证；`aforge-darwin-x64` 既无免费 runner 也无法用容器模拟，属于「已交叉编译但完全未冒烟」。
|
|
55
|
-
|
|
56
|
-
### 方式三：从源码构建
|
|
57
|
-
|
|
58
|
-
前置：安装 [bun](https://bun.sh/) 与 [fnm](https://github.com/Schniz/fnm)（或任意 Node 版本管理器）。
|
|
59
|
-
|
|
60
|
-
```powershell
|
|
61
|
-
# 每个新终端先激活 Node 环境（fnm）
|
|
62
|
-
fnm env --shell power-shell | Out-String -Stream | Invoke-Expression
|
|
63
|
-
fnm use 22
|
|
64
|
-
|
|
65
|
-
git clone https://github.com/zyTheGit/AgentForge.git
|
|
66
|
-
cd AgentForge
|
|
67
|
-
npm install
|
|
68
|
-
|
|
69
|
-
npm run build:node # 产出 dist\aforge.js（esbuild 打包压缩，需 Node ≥ 20.19）
|
|
70
|
-
npm run build:bun # 产出当前平台的单文件二进制（dist\aforge-win32-x64.exe 等）
|
|
71
|
-
npm run build:bun:all # 交叉编译五平台（win32-x64 / linux-x64 / linux-arm64 / darwin-x64 / darwin-arm64）
|
|
72
|
-
bun link # 之后任意目录可用 aforge 命令
|
|
21
|
+
npx -y @zythegit/agentforge@latest --version # 免安装试跑
|
|
22
|
+
npm i -g @zythegit/agentforge # 常用则全局装，命令名是 aforge
|
|
73
23
|
```
|
|
74
24
|
|
|
75
|
-
|
|
76
|
-
|
|
25
|
+
免 Node 的独立二进制、从源码构建、macOS / Linux 差异见 [docs/install.md](docs/install.md)。
|
|
77
26
|
|
|
78
|
-
##
|
|
27
|
+
## 快速开始
|
|
79
28
|
|
|
80
29
|
```powershell
|
|
81
|
-
# 进入你的项目
|
|
82
30
|
cd C:\path\to\your-project
|
|
83
31
|
|
|
84
32
|
# ① 交互式初始化：选 scope → 自动探测工具链 → 确认 → 选目标 Agent → 写入（可选立即 sync）
|
|
@@ -101,27 +49,18 @@ aforge sync
|
|
|
101
49
|
aforge import AGENTS.md # 或 CLAUDE.md：识别工具链关键词 → habits 建议字段 + custom 素材
|
|
102
50
|
```
|
|
103
51
|
|
|
104
|
-
##
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
| `aforge source list [--json]` / `remove <id>` / `update <id>` | 管理已登记来源（update 离线报错） |
|
|
117
|
-
| `aforge template list [--json]` / `enable <id>` / `disable <id>` | 管理规则模板 |
|
|
118
|
-
| `aforge skill add <name> [--from src]` / `list [--json]` | 安装（实体拷贝）/列出技能 |
|
|
119
|
-
| `aforge mcp add [--scope s] [--from-json] [--json]` | 登记 MCP 服务器声明（`--from-json` 从 stdin 读 JSON 声明） |
|
|
120
|
-
| `aforge status [--json]` | SoT 概览：scope、目标路径、最近 sync、内容计数 |
|
|
121
|
-
| `aforge doctor [--json]` | 体检：配置合法性、投影一致性、环境问题 |
|
|
122
|
-
| `aforge import <path>` | 从既有 AGENTS.md / CLAUDE.md 导入工具链声明与素材 |
|
|
123
|
-
|
|
124
|
-
`--json` 同时是 program 级全局标志：任何子命令都可写成 `aforge --json <cmd>`，输出为机器可读 JSON（路径一律绝对路径）。注意 `mcp add` 的**输入**标志叫 `--from-json`，`--json` 只表示输出契约。
|
|
52
|
+
## 常用指令
|
|
53
|
+
|
|
54
|
+
```powershell
|
|
55
|
+
aforge status # SoT 概览：scope、各 target 落点与技能调用前缀、最近一次 sync
|
|
56
|
+
aforge doctor # 体检：配置合法性、投影一致性、环境问题
|
|
57
|
+
aforge sync --dry-run # 只看会写哪些文件，不落盘
|
|
58
|
+
aforge learn # 记一条 learning（不投影，promote 后才进规则）
|
|
59
|
+
aforge skill add <name> # 装技能进 SoT 并登记，sync 后投影到四家
|
|
60
|
+
aforge mcp add # 登记 MCP 服务器，sync 时翻译成各 Agent 的原生配置
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
任何子命令都可加 `--json` 拿机器可读输出（路径一律绝对路径）。完整 14 个命令、参数与退出码见 [命令速查](docs/commands.md)。
|
|
125
64
|
|
|
126
65
|
## 工作原理
|
|
127
66
|
|
|
@@ -136,7 +75,13 @@ aforge import AGENTS.md # 或 CLAUDE.md：识别工具链关键词 → habits
|
|
|
136
75
|
└────────────────────────────┘
|
|
137
76
|
```
|
|
138
77
|
|
|
139
|
-
|
|
78
|
+
规则文件之外，同一次 `sync` 还落三类**整文件产物**（不用 marker，改名/摘名后由下一次 `sync` prune）：
|
|
79
|
+
|
|
80
|
+
- **技能**：`skills/<name>/SKILL.md` 投影到四家各自的技能目录，`status` 会打出每家的调用前缀；
|
|
81
|
+
- **MCP**：一份 `profile.mcp.servers` 翻译成 opencode / codex / claude / pi 的原生配置；
|
|
82
|
+
- **命令薄壳**：`skills.expose_as_command` 点名的技能额外落一份命令/prompt，支持 `ns/name` 命名空间与 `$1..$9` 位置参数（见 [技能](docs/skills.md#额外投影成命令expose_as_command)）。
|
|
83
|
+
|
|
84
|
+
每个投影的**规则文件**中，AgentForge 只管理 marker 区间：
|
|
140
85
|
|
|
141
86
|
```markdown
|
|
142
87
|
<!-- BEGIN AGENTFORGE -->
|
|
@@ -148,70 +93,20 @@ aforge import AGENTS.md # 或 CLAUDE.md：识别工具链关键词 → habits
|
|
|
148
93
|
|
|
149
94
|
- **变更检测**：sync 前对比 marker 区间指纹，发现你手改过区间内容 → 拒绝写入（退出码 3），`--force` 可覆盖；
|
|
150
95
|
- **事务化写入**：多 target 投影失败自动回滚已写文件；
|
|
151
|
-
- **两级合并**：user 层 SoT 与 project 层 SoT 按层合并（project
|
|
152
|
-
|
|
153
|
-
## Windows 注意事项
|
|
154
|
-
|
|
155
|
-
- **路径**：统一使用绝对路径输出；用户级 SoT 默认在 `%USERPROFILE%\.agentforge`，项目级在 `<项目根>\.agentforge`。含中文与空格的路径已受测试覆盖，可放心使用。
|
|
156
|
-
- **换行**：投影文件默认 LF（可通过 `profile.yaml` 的 `projection.line_ending: crlf` 修改）；SoT 内部素材统一 LF，换行差异由投影层吸收，不会造成虚假 diff。
|
|
157
|
-
- **离线**：无网络环境完全可用（init/sync/template/skill 等纯本地操作）。git 源的 `source update` 需要网络，离线时明确报错（退出码 5）。也可设 `AGF_OFFLINE=1` 显式声明离线意图，让需要网络的操作尽早失败。
|
|
158
|
-
- **权限**：**无需 Administrator**。全部文件读写都在你的用户目录与项目目录内；写失败时给出可操作的修复提示（退出码 4）。
|
|
159
|
-
- **控制台编码**：非交互命令输出为纯 ASCII（GBK 代码页 `chcp 936` 下不乱码）；`init -i` 的交互 UI 需要真实终端（TTY）。
|
|
160
|
-
|
|
161
|
-
### 环境变量
|
|
162
|
-
|
|
163
|
-
| 变量 | 作用 |
|
|
164
|
-
|------|------|
|
|
165
|
-
| `AGF_SCOPE` | 缺省 scope（`project` / `user`） |
|
|
166
|
-
| `AGF_HOME` | 覆盖用户级 SoT 根目录 |
|
|
167
|
-
| `AGF_LINE_ENDING` | 覆盖投影换行风格（`crlf` / `lf`） |
|
|
168
|
-
| `AGF_OFFLINE` | 设为 `1` 声明离线模式 |
|
|
169
|
-
|
|
170
|
-
## 退出码约定
|
|
171
|
-
|
|
172
|
-
| 码 | 含义 |
|
|
173
|
-
|----|------|
|
|
174
|
-
| 0 | 成功 |
|
|
175
|
-
| 2 | 配置错误（未初始化、非法参数、非 TTY 环境跑交互命令等） |
|
|
176
|
-
| 3 | 冲突（marker 区间被手改，拒绝覆盖） |
|
|
177
|
-
| 4 | 权限错误（目标不可写） |
|
|
178
|
-
| 5 | 离线（需要网络的操作在离线模式下失败） |
|
|
179
|
-
|
|
180
|
-
## 已知限制
|
|
181
|
-
|
|
182
|
-
- **并发安全**：多进程并发执行 `aforge sync` 或 `aforge source add` 等行为未定义。建议避免并发操作同一 SoT 目录（`.agentforge/`）。如需自动化调度，请确保串行执行。
|
|
183
|
-
- **Symlink 支持**：`skills/` 目录默认使用实体拷贝（`copy_mode: copy`），不使用 symlink。跨平台场景（尤其 Windows）symlink 可能失败，doctor 会检测并提示。
|
|
184
|
-
|
|
185
|
-
## macOS / Linux 旁注
|
|
186
|
-
|
|
187
|
-
- 首选装法与 Windows 一致：`npx -y @zythegit/agentforge@latest`（或 `npm i -g`）；
|
|
188
|
-
- 从源码构建：`fnm env --shell bash | source -`（或 zsh）后 `npm install` + `npm run build:node`；
|
|
189
|
-
- 用户级 SoT 在 `$HOME/.agentforge`；投影换行默认规则同 Windows（profile 可配置）；
|
|
190
|
-
- `npm run build:bun` 自动按当前平台选 target，`build:bun:all` 一次交叉编译五平台；
|
|
191
|
-
- macOS 二进制未签名未公证，见上文「方式二」的 `xattr` 说明。
|
|
192
|
-
|
|
193
|
-
## 开发
|
|
194
|
-
|
|
195
|
-
```powershell
|
|
196
|
-
fnm env --shell power-shell | Out-String -Stream | Invoke-Expression
|
|
197
|
-
fnm use 22
|
|
198
|
-
npm install
|
|
199
|
-
npm test # 全量测试（vitest）
|
|
200
|
-
npm run typecheck # tsc --noEmit
|
|
201
|
-
npm run build # 双轨构建（node + bun）
|
|
202
|
-
```
|
|
203
|
-
|
|
204
|
-
## 发布
|
|
205
|
-
|
|
206
|
-
版本号唯一来源是 git tag：推送 `v1.2.3` 触发 `.github/workflows/release.yml`，它把版本写进 `package.json` → `src/version.ts`（`scripts/gen-version.mjs`），发布 npm 包，并把五平台二进制压缩包挂到 Release。
|
|
96
|
+
- **两级合并**：user 层 SoT 与 project 层 SoT 按层合并（project 优先）；
|
|
97
|
+
- **环境无关**：投影正文不受 `CI` 等环境变量影响，同一份 SoT 在 CI 与本机渲染出的 `contentHash` 一致，`aforge doctor` 的 hash 比对才不会误报漂移。
|
|
207
98
|
|
|
208
|
-
|
|
209
|
-
- 带连字符的 tag（`v1.2.3-rc.1`）发到 npm 的 `next` 频道，不抢占 `latest`。
|
|
210
|
-
- 需要仓库 secret `NPM_TOKEN`（npm Automation token）。
|
|
211
|
-
- 本地预演：`npm pack` 后 `npx ./zythegit-agentforge-<ver>.tgz --version`。
|
|
99
|
+
## 文档
|
|
212
100
|
|
|
213
|
-
|
|
101
|
+
- [命令速查与约定](docs/commands.md)——14 个命令、`--json` 契约、环境变量、退出码
|
|
102
|
+
- [安装与构建](docs/install.md)——三种装法、双轨构建、开发命令
|
|
103
|
+
- [技能](docs/skills.md)——登记来源、安装、投影落点与调用前缀，以及 `expose_as_command` 命令薄壳（命名空间、`$1..$9`）
|
|
104
|
+
- [MCP](docs/mcp.md)——一份声明翻译成四家的原生配置
|
|
105
|
+
- [learning](docs/learning.md)——`learn` / `promote` 闭环与 `auto_capture`
|
|
106
|
+
- [迁移 SoT](docs/bundle.md)——`bundle export/import` 换机器、备份
|
|
107
|
+
- [平台注意事项与已知限制](docs/platform.md)——Windows 路径 / 换行 / 编码，并发与 symlink 边界，尚未实现的字段
|
|
108
|
+
- 规格与需求：[AgentForge-Spec.md](AgentForge-Spec.md)、[AgentForge-PRD.md](AgentForge-PRD.md)
|
|
214
109
|
|
|
215
110
|
---
|
|
216
111
|
|
|
217
|
-
|
|
112
|
+
*版本以 git tag 为唯一来源（`v*` tag → npm 包版本 + Release 资产），本机版本用 `aforge --version` 查。*
|