harnessed 1.0.0 → 1.0.1
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 +151 -110
- package/dist/cli.mjs +107 -38
- package/dist/cli.mjs.map +1 -1
- package/dist/index.mjs +1 -1
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,178 +1,219 @@
|
|
|
1
1
|
# harnessed
|
|
2
2
|
|
|
3
|
-
>
|
|
4
|
-
>
|
|
3
|
+
> AI coding harness 包管理器 + composition orchestrator
|
|
4
|
+
> 把 CLAUDE.md 三层栈协作规则机器化为可执行 engine
|
|
5
5
|
|
|
6
|
-
[](./LICENSE)
|
|
7
6
|
[](https://npmjs.com/package/harnessed)
|
|
7
|
+
[](./LICENSE)
|
|
8
8
|
[](https://github.com/sponsors/easyinplay)
|
|
9
9
|
|
|
10
|
-
> Not affiliated with, endorsed by, or sponsored by Harness Inc
|
|
11
|
-
|
|
12
|
-
## 一句话定位
|
|
10
|
+
> Not affiliated with, endorsed by, or sponsored by Harness Inc. (见 [NOTICE](./NOTICE))
|
|
13
11
|
|
|
14
|
-
|
|
12
|
+
---
|
|
15
13
|
|
|
16
|
-
##
|
|
14
|
+
## ✨ 一句话定位
|
|
17
15
|
|
|
18
|
-
|
|
19
|
-
- **不 vendor**（base layer）：上游代码不进我们仓库，靠 manifest 描述 install/check（schema v1 frozen — see [ADR 0001](./docs/adr/0001-manifest-schema-v1.md)；phase 1.3 加 categorization 3 字段 errata see [ADR 0007](./docs/adr/0007-categorization-schema-extension.md)）
|
|
20
|
-
- **Composition Skill**：自家 workflow skill 当指挥棒，调度多个上游协同（research / execute-task / plan-feature 三 MVP workflow）
|
|
21
|
-
- **包管理器思维**：`harnessed install <workflow>` 自动解析依赖图、`doctor` 健康检查、`install-base` 一键装齐 base profile（10 固定 manifest）
|
|
22
|
-
- **强意见 vs all-in-one**：用户面对 `/harnessed:*` 统一入口，不需学每家上游术语
|
|
16
|
+
装配市面上最优秀的开源 Claude Code 生态组件,用强意见 composition skill 织成统一工作流;不 vendor 上游代码,通过 manifest 描述 install/check + composition skill 编排多上游协作。
|
|
23
17
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
```
|
|
27
|
-
harnessed/
|
|
28
|
-
├── manifests/ # 上游描述层（不 vendor）
|
|
29
|
-
│ ├── tools/ # cc-plugin / mcp-npm / cli-npm
|
|
30
|
-
│ └── skill-packs/ # cc-skill-pack
|
|
31
|
-
├── workflows/ # composition skill（指挥棒）
|
|
32
|
-
├── routing/ # B+C 混合路由 SSOT
|
|
33
|
-
├── config-templates/ # 配置注入层（hooks 等）
|
|
34
|
-
├── schemas/ # JSON Schema artifact (publish 给 IDE / CI)
|
|
35
|
-
├── src/ # TS 源码（installer / validator / router / checkpoint）
|
|
36
|
-
├── tests/ # vitest 单测 + 集成 + bench
|
|
37
|
-
└── docs/adr/ # 架构决策记录
|
|
38
|
-
```
|
|
18
|
+
---
|
|
39
19
|
|
|
40
|
-
##
|
|
20
|
+
## 🎯 关键差异化
|
|
41
21
|
|
|
42
|
-
-
|
|
43
|
-
-
|
|
44
|
-
- **
|
|
22
|
+
- **三层栈机器化** — `gstack 决策` + `GSD 项目经理` + `superpowers 资深工程师` + `karpathy 4 心法` + `mattpocock 23 招式`,5 支柱 100% capture
|
|
23
|
+
- **不 vendor 上游** — manifest describe install/check;上游升级用户 re-install 即获最新版
|
|
24
|
+
- **Composition Skill** — 自家 workflow skill 当指挥棒,调度多个上游协同 (research / execute-task / plan-feature 三 MVP workflow)
|
|
25
|
+
- **包管理器思维** — install dependency graph 自动解析, doctor 健康检查, install-base 一键装齐
|
|
26
|
+
- **统一入口** — 用户面对 `/harnessed:*`, 不需学每家上游术语
|
|
45
27
|
|
|
46
|
-
|
|
28
|
+
---
|
|
47
29
|
|
|
48
|
-
|
|
30
|
+
## 📦 快速安装
|
|
49
31
|
|
|
50
32
|
```bash
|
|
51
|
-
|
|
52
|
-
|
|
33
|
+
npm install -g harnessed
|
|
34
|
+
```
|
|
53
35
|
|
|
54
|
-
|
|
55
|
-
harnessed install ctx7 --apply
|
|
36
|
+
或不全局安装 (ephemeral 模式):
|
|
56
37
|
|
|
57
|
-
|
|
58
|
-
harnessed
|
|
38
|
+
```bash
|
|
39
|
+
npx harnessed@latest <command>
|
|
40
|
+
```
|
|
59
41
|
|
|
60
|
-
|
|
61
|
-
harnessed status
|
|
62
|
-
harnessed backup list
|
|
63
|
-
harnessed gc --older-than 30d --apply
|
|
42
|
+
---
|
|
64
43
|
|
|
65
|
-
|
|
66
|
-
harnessed rollback 2026-05-12T15:30:00Z
|
|
44
|
+
## 🚩 命令一览
|
|
67
45
|
|
|
68
|
-
|
|
69
|
-
harnessed doctor
|
|
70
|
-
```
|
|
46
|
+
### 主命令
|
|
71
47
|
|
|
72
|
-
|
|
48
|
+
| 命令 | 说明 |
|
|
49
|
+
| ---- | ---- |
|
|
50
|
+
| `harnessed setup` | 一次性 setup,装 workflow skills 到 `~/.claude/skills/` |
|
|
51
|
+
| `harnessed install <name>` | 装上游 manifest (默认 dry-run) |
|
|
52
|
+
| `harnessed uninstall <name>` | 反向卸载 (默认 dry-run) |
|
|
53
|
+
| `harnessed audit-log` | 路由透明日志 query (支持 `--filter` jq 表达式) |
|
|
54
|
+
| `harnessed status` | 当前 phase + lock holder |
|
|
55
|
+
| `harnessed resume` | session 中断后恢复至最近 checkpoint |
|
|
56
|
+
| `harnessed doctor` | 8-check 健康检查 (Node / MCP / jq / Win bash / 路由 / token budget 等) |
|
|
57
|
+
| `harnessed backup` | snapshot 备份管理 |
|
|
58
|
+
| `harnessed rollback <timestamp>` | 一行回滚 (EOL preserve + sha1 verify) |
|
|
59
|
+
| `harnessed gc` | 清理过期 backups |
|
|
60
|
+
|
|
61
|
+
### 参数 (Flags)
|
|
73
62
|
|
|
74
63
|
| Flag | 说明 |
|
|
75
64
|
| ---- | ---- |
|
|
76
|
-
| `--apply` |
|
|
77
|
-
| `--dry-run` |
|
|
78
|
-
| `--
|
|
79
|
-
| `--
|
|
65
|
+
| `--apply` | 显式执行 (默认 dry-run) |
|
|
66
|
+
| `--dry-run` | 永不写盘 (即使加 `--apply` 也优先 dry-run) |
|
|
67
|
+
| `--non-interactive` | CI / 脚本场景;必须配合 `--apply` 或 `--dry-run` |
|
|
68
|
+
| `--system` | L4 全局装允许 (否则降级 L1 npx ephemeral) |
|
|
69
|
+
| `--yes` | uninstall 跳过交互 confirm |
|
|
80
70
|
| `--full-diff` | 展开 > 200 行的 diff 折叠 |
|
|
81
|
-
| `--no-color` | 强制 nocolor
|
|
71
|
+
| `--no-color` | 强制 nocolor (即使 TTY) |
|
|
82
72
|
|
|
83
|
-
|
|
73
|
+
---
|
|
84
74
|
|
|
85
|
-
|
|
75
|
+
## ⚡ 使用流程
|
|
86
76
|
|
|
87
|
-
harnessed
|
|
77
|
+
`/harnessed:plan-feature "新功能 X"` 一行触发 CLAUDE.md 4-stage 三层栈方法论:
|
|
88
78
|
|
|
89
|
-
|
|
79
|
+
```
|
|
80
|
+
① Discuss → ② Plan → ③ Execute → ④ Verify
|
|
81
|
+
```
|
|
90
82
|
|
|
91
|
-
|
|
83
|
+
| Stage | 上游协同 | 职责 |
|
|
84
|
+
| ---- | ---- | ---- |
|
|
85
|
+
| ① **Discuss** | gstack `/office-hours` + GSD `/gsd-discuss-phase` | 多角色决策 + 灰色澄清 |
|
|
86
|
+
| ② **Plan** | GSD `/gsd-plan-phase` + planning-with-files | 任务拆解 + 持久化 `task_plan.md` |
|
|
87
|
+
| ③ **Execute** | superpowers brainstorm + karpathy 心法 + mattpocock 招式 + ralph-loop | 子任务至 verbatim `COMPLETE` |
|
|
88
|
+
| ④ **Verify** | GSD `/gsd-verify-work` + code-review + gstack `/review` + code-simplifier | 多角度审查 + 简化 |
|
|
92
89
|
|
|
93
|
-
|
|
94
|
-
# 1. 一次性 setup（装 workflow skills 到 ~/.claude/skills/、配置 hooks）
|
|
95
|
-
npx harnessed@latest setup
|
|
90
|
+
实操示例:
|
|
96
91
|
|
|
97
|
-
|
|
92
|
+
```bash
|
|
93
|
+
# 1. 装 workflow 上游 (一行装齐 gstack + GSD + superpowers + planning-with-files)
|
|
98
94
|
harnessed install plan-feature
|
|
99
|
-
# → 自动装 gstack + superpowers + GSD + planning-with-files
|
|
100
95
|
|
|
101
|
-
#
|
|
96
|
+
# 2. 在 Claude Code 内跑
|
|
102
97
|
/harnessed:plan-feature "新功能 X"
|
|
103
|
-
# → 调度 5 phase: gstack governance → superpowers brainstorm → GSD discuss/plan → planning-with-files persist
|
|
104
|
-
# → 暂停点等用户 approve（CEO veto / final task_plan lock）
|
|
105
98
|
|
|
106
|
-
#
|
|
107
|
-
harnessed
|
|
108
|
-
|
|
99
|
+
# 3. 中断后恢复 (任何时候)
|
|
100
|
+
harnessed resume
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
📊 详细 mermaid + 各 stage 完整说明:[docs/WORKFLOW.md](./docs/WORKFLOW.md)
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
## 🗂️ 项目结构
|
|
109
108
|
|
|
110
|
-
|
|
111
|
-
harnessed
|
|
109
|
+
```
|
|
110
|
+
harnessed/
|
|
111
|
+
├── manifests/ # 上游描述层 (不 vendor)
|
|
112
|
+
│ ├── tools/ # CLI / MCP / hooks
|
|
113
|
+
│ └── skill-packs/ # Claude Code skill packs
|
|
114
|
+
├── workflows/ # composition skill (指挥棒)
|
|
115
|
+
├── routing/ # 路由 SSOT (B+C 混合)
|
|
116
|
+
├── schemas/ # JSON Schema artifact (IDE / CI consume)
|
|
117
|
+
├── src/ # TS 源码 (installer / validator / router / checkpoint / audit)
|
|
118
|
+
├── tests/ # vitest 单测 + 集成 + bench
|
|
119
|
+
└── docs/adr/ # 架构决策记录 (ADR 0001-0023)
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
## ❓ FAQ
|
|
125
|
+
|
|
126
|
+
<details>
|
|
127
|
+
<summary><b>Q1. 装了 harnessed 还需要装 superpowers / gstack / GSD 上游吗?</b></summary>
|
|
128
|
+
|
|
129
|
+
<br>
|
|
130
|
+
|
|
131
|
+
需要,但**用户感知 = 一行命令**:
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
harnessed install plan-feature # 自动装齐 gstack + GSD + superpowers + planning-with-files
|
|
112
135
|
```
|
|
113
136
|
|
|
114
|
-
|
|
137
|
+
类比 `brew install <formula>` 装全套依赖 — 你不需要单独 `brew install` 每个依赖项。
|
|
115
138
|
|
|
116
|
-
|
|
139
|
+
</details>
|
|
117
140
|
|
|
118
|
-
|
|
141
|
+
<details>
|
|
142
|
+
<summary><b>Q2. 为什么不直接 vendor superpowers / gstack 进 harnessed 仓库?</b></summary>
|
|
119
143
|
|
|
120
|
-
|
|
144
|
+
<br>
|
|
121
145
|
|
|
122
|
-
4
|
|
146
|
+
4 条理由:
|
|
123
147
|
|
|
124
|
-
1.
|
|
125
|
-
2. **License + attribution
|
|
126
|
-
3.
|
|
127
|
-
4. **Bus factor 1
|
|
148
|
+
1. **差异化哲学** — harnessed 是「装配主义包管理器」对位「all-in-one 自建派」。vendor = 失去 wedge → 沦为又一个 plugin pack
|
|
149
|
+
2. **License + attribution 噩梦** — vendor 4-5 个主动维护的上游 = 复杂 license 拼盘
|
|
150
|
+
3. **上游升级反向** — 当前 manifest 描述,上游升级用户 re-install 即得新版;vendor 后手动 sync code 永远落后
|
|
151
|
+
4. **Bus factor 1** — 单 maintainer 维护 vendor 4-5 上游 = 加速 burnout
|
|
128
152
|
|
|
129
|
-
|
|
153
|
+
</details>
|
|
130
154
|
|
|
131
|
-
|
|
155
|
+
<details>
|
|
156
|
+
<summary><b>Q3. gstack / GSD / superpowers 看起来都是 plan/discuss 类,是不是重叠?</b></summary>
|
|
157
|
+
|
|
158
|
+
<br>
|
|
159
|
+
|
|
160
|
+
**不是**。它们是三层栈的不同阶段:
|
|
132
161
|
|
|
133
162
|
| 阶段 | 上游 | 职责 |
|
|
134
|
-
|
|
135
|
-
| Governance | gstack |
|
|
163
|
+
| ---- | ---- | ---- |
|
|
164
|
+
| Governance | gstack | 多角色决策关卡 (CEO / EM / Designer / Paranoid Engineer) |
|
|
136
165
|
| Brainstorming | superpowers | 子任务设计澄清、方案对比 |
|
|
137
166
|
| Orchestration | GSD | 高层 phase 任务图 + 依赖分析 |
|
|
138
|
-
| Persistence | planning-with-files | 持久化 task_plan / progress / findings
|
|
167
|
+
| Persistence | planning-with-files | 持久化 `task_plan.md` / `progress.md` / `findings.md` |
|
|
168
|
+
|
|
169
|
+
`/harnessed:plan-feature` 把 4 阶段串起来 — 每个阶段做不同事,输出喂给下一阶段。**没有合并**。
|
|
170
|
+
|
|
171
|
+
</details>
|
|
172
|
+
|
|
173
|
+
<details>
|
|
174
|
+
<summary><b>Q4. workflow phase 之间是自动跑还是等用户?</b></summary>
|
|
139
175
|
|
|
140
|
-
|
|
176
|
+
<br>
|
|
141
177
|
|
|
142
|
-
|
|
178
|
+
看 `workflows/<name>/SKILL.md` frontmatter 的 `pause` 字段:
|
|
143
179
|
|
|
144
|
-
|
|
180
|
+
- `pause: human_review` → 阻塞等用户 approve (governance gate / final lock,如 `plan-feature` 的 phase 01 + 05)
|
|
181
|
+
- 无 `pause` → 自动 chain 到下一 phase
|
|
145
182
|
|
|
146
|
-
|
|
147
|
-
- 无 `pause` → 自动 chain 到下一 phase（中间步骤）
|
|
183
|
+
每个 phase 输出写到 `.harnessed/checkpoints/`,session 中断后 `harnessed resume` 从最近 checkpoint 继续。
|
|
148
184
|
|
|
149
|
-
|
|
185
|
+
</details>
|
|
150
186
|
|
|
151
|
-
|
|
187
|
+
<details>
|
|
188
|
+
<summary><b>Q5. harnessed 自己是 CC plugin 吗?</b></summary>
|
|
152
189
|
|
|
153
|
-
|
|
190
|
+
<br>
|
|
154
191
|
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
-
|
|
192
|
+
混合体:
|
|
193
|
+
|
|
194
|
+
- `npx harnessed@latest setup` 跑的是 **Node.js CLI** (`bin/harnessed`)
|
|
195
|
+
- setup 装的 **workflow skills** (markdown) 进 `~/.claude/skills/`,由 Claude Code 运行时加载
|
|
196
|
+
- `/harnessed:*` 是 CC 内的 slash command,触发 skill 执行
|
|
158
197
|
- CLI 和 CC skill 共享 `.harnessed/checkpoints/` 状态目录
|
|
159
198
|
|
|
160
|
-
|
|
199
|
+
</details>
|
|
161
200
|
|
|
162
|
-
|
|
163
|
-
- [WORKFLOWS-MVP.md](./WORKFLOWS-MVP.md) — 3 个 MVP workflow 展开（v2.1）
|
|
164
|
-
- [docs/adr/](./docs/adr/) — 架构决策记录（17 ADRs 0001-0017）｜[docs/WORKFLOW.md](./docs/WORKFLOW.md) — 项目实际 dev 工作流 mermaid + 16-phase cadence 模式表 + CLAUDE.md gap 分析
|
|
165
|
-
- [.planning/ROADMAP.md](./.planning/ROADMAP.md) — 4 milestones × 3-5 phases 路线图
|
|
166
|
-
- [.planning/STATE.md](./.planning/STATE.md) — 跨 session 项目记忆 SSOT
|
|
167
|
-
- [CONTRIBUTING.md](./CONTRIBUTING.md) — 贡献指南（含 Windows corepack ACL workaround）
|
|
168
|
-
- [SECURITY.md](./SECURITY.md) — 漏洞披露通道
|
|
201
|
+
---
|
|
169
202
|
|
|
170
|
-
##
|
|
203
|
+
## 📚 文档导航
|
|
171
204
|
|
|
172
|
-
|
|
205
|
+
- [docs/WORKFLOW.md](./docs/WORKFLOW.md) — 4-stage workflow mermaid + 各 stage 详解
|
|
206
|
+
- [docs/INSTALLER-CONTRACT.md](./docs/INSTALLER-CONTRACT.md) — installer 6 条用户视角硬契约
|
|
207
|
+
- [docs/MAINTAINER-ONBOARDING.md](./docs/MAINTAINER-ONBOARDING.md) — 30 分钟跑通 dev 环境
|
|
208
|
+
- [docs/adr/](./docs/adr/) — 架构决策记录 (ADR 0001-0023)
|
|
209
|
+
- [CHANGELOG.md](./CHANGELOG.md) — 完整版本历史
|
|
210
|
+
- [CONTRIBUTING.md](./CONTRIBUTING.md) — 贡献指南
|
|
211
|
+
- [SECURITY.md](./SECURITY.md) — 漏洞披露通道
|
|
173
212
|
|
|
174
|
-
|
|
213
|
+
---
|
|
175
214
|
|
|
176
215
|
## License
|
|
177
216
|
|
|
178
|
-
[Apache-2.0](./LICENSE) — 见 [NOTICE](./NOTICE)
|
|
217
|
+
[Apache-2.0](./LICENSE) — 见 [NOTICE](./NOTICE) (含 Harness Inc. 商标 disclaimer)
|
|
218
|
+
|
|
219
|
+
支持开发: [](https://github.com/sponsors/easyinplay)
|