dsh-harness-kit 0.0.0-stage → 0.1.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.
Files changed (87) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +321 -2
  3. package/README.zh-CN.md +278 -0
  4. package/client.js +1272 -0
  5. package/cordis.patch.yml +4 -0
  6. package/docs/DETAIL.en.md +97 -0
  7. package/docs/DETAIL.md +73 -0
  8. package/docs/assets/ui-new-task.png +0 -0
  9. package/docs/assets/ui-onboarding.png +0 -0
  10. package/docs/assets/ui-war-room.png +0 -0
  11. package/icon.svg +7 -0
  12. package/index.js +49 -0
  13. package/kernel/advance.js +96 -0
  14. package/kernel/bindings.js +24 -0
  15. package/kernel/commands.js +927 -0
  16. package/kernel/env.js +64 -0
  17. package/kernel/exec.js +41 -0
  18. package/kernel/flows.js +89 -0
  19. package/kernel/guards.js +79 -0
  20. package/kernel/miniyaml.js +133 -0
  21. package/kernel/models.js +104 -0
  22. package/kernel/panel.js +1103 -0
  23. package/kernel/paths.js +53 -0
  24. package/kernel/roles.js +67 -0
  25. package/kernel/setup.js +644 -0
  26. package/kernel/state.js +59 -0
  27. package/kernel/steer.js +27 -0
  28. package/kernel/sync.js +140 -0
  29. package/kernel/te.js +122 -0
  30. package/kernel/worktree.js +868 -0
  31. package/locale/en.json +14 -0
  32. package/locale/zh.json +14 -0
  33. package/package.json +63 -4
  34. package/packs/ai-coding/agents/business-analyst.md +90 -0
  35. package/packs/ai-coding/agents/code-reviewer.md +156 -0
  36. package/packs/ai-coding/agents/developer.md +147 -0
  37. package/packs/ai-coding/agents/project-manager.md +190 -0
  38. package/packs/ai-coding/agents/readiness-reviewer.md +123 -0
  39. package/packs/ai-coding/agents/solution-architect.md +122 -0
  40. package/packs/ai-coding/agents/test-engineer.md +230 -0
  41. package/packs/ai-coding/assets/scripts/check_codegraph.py +215 -0
  42. package/packs/ai-coding/assets/scripts/codebase_guide_init.py +330 -0
  43. package/packs/ai-coding/assets/scripts/env_auto.py +612 -0
  44. package/packs/ai-coding/assets/scripts/harness.py +38 -0
  45. package/packs/ai-coding/assets/scripts/harness_init.py +193 -0
  46. package/packs/ai-coding/assets/scripts/lib.py +1011 -0
  47. package/packs/ai-coding/assets/scripts/run_field.py +295 -0
  48. package/packs/ai-coding/assets/scripts/spec_lint.py +247 -0
  49. package/packs/ai-coding/assets/scripts/update_board.py +524 -0
  50. package/packs/ai-coding/assets/scripts/verify.py +184 -0
  51. package/packs/ai-coding/assets/templates/dotnet/dotnet-multimodule/CODE_STANDARDS.tmpl +44 -0
  52. package/packs/ai-coding/assets/templates/dotnet/dotnet-multimodule/app-CLAUDE.tmpl +34 -0
  53. package/packs/ai-coding/assets/templates/dotnet/dotnet-multimodule/build.tmpl +8 -0
  54. package/packs/ai-coding/assets/templates/dotnet/dotnet-multimodule/module-CLAUDE.tmpl +42 -0
  55. package/packs/ai-coding/assets/templates/dotnet/dotnet-multimodule/root-CLAUDE.tmpl +41 -0
  56. package/packs/ai-coding/assets/templates/java/maven/CODE_STANDARDS.tmpl +44 -0
  57. package/packs/ai-coding/assets/templates/java/maven/build.tmpl +9 -0
  58. package/packs/ai-coding/assets/templates/java/maven/root-CLAUDE.tmpl +38 -0
  59. package/packs/ai-coding/assets/templates/java/maven-multimodule/CODE_STANDARDS.tmpl +44 -0
  60. package/packs/ai-coding/assets/templates/java/maven-multimodule/build.tmpl +9 -0
  61. package/packs/ai-coding/assets/templates/java/maven-multimodule/module-CLAUDE.tmpl +40 -0
  62. package/packs/ai-coding/assets/templates/java/maven-multimodule/root-CLAUDE.tmpl +38 -0
  63. package/packs/ai-coding/assets/templates/javascript/mobile-app/CODE_STANDARDS.tmpl +51 -0
  64. package/packs/ai-coding/assets/templates/javascript/mobile-app/build.tmpl +8 -0
  65. package/packs/ai-coding/assets/templates/javascript/mobile-app/root-CLAUDE.tmpl +36 -0
  66. package/packs/ai-coding/assets/templates/javascript/uniapp/CODE_STANDARDS.tmpl +69 -0
  67. package/packs/ai-coding/assets/templates/javascript/uniapp/build.tmpl +8 -0
  68. package/packs/ai-coding/assets/templates/javascript/uniapp/root-CLAUDE.tmpl +56 -0
  69. package/packs/ai-coding/assets/templates/javascript/vue-multimodule/CODE_STANDARDS.tmpl +51 -0
  70. package/packs/ai-coding/assets/templates/javascript/vue-multimodule/app-CLAUDE.tmpl +36 -0
  71. package/packs/ai-coding/assets/templates/javascript/vue-multimodule/build.tmpl +8 -0
  72. package/packs/ai-coding/assets/templates/javascript/vue-multimodule/root-CLAUDE.tmpl +34 -0
  73. package/packs/ai-coding/flows/_router.yml +14 -0
  74. package/packs/ai-coding/flows/bugfix.yml +37 -0
  75. package/packs/ai-coding/flows/fix.yml +44 -0
  76. package/packs/ai-coding/flows/init.yml +83 -0
  77. package/packs/ai-coding/flows/new.yml +29 -0
  78. package/packs/ai-coding/flows/quick.yml +40 -0
  79. package/packs/ai-coding/flows/refactor.yml +50 -0
  80. package/packs/ai-coding/flows/standard.yml +49 -0
  81. package/packs/ai-coding/rules/code-standards.md +30 -0
  82. package/packs/ai-coding/rules/core.md +83 -0
  83. package/packs/ai-coding/templates/bugfix.md +29 -0
  84. package/packs/ai-coding/templates/memory-entry.md +46 -0
  85. package/packs/ai-coding/templates/proposal.md +47 -0
  86. package/packs/ai-coding/templates/spec-template.md +34 -0
  87. package/screenshots.json +5 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 leo
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,322 @@
1
- # Temporary Holding Version
1
+ # Harness Kit
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **Turn AI coding from a personal habit into a team process.**
4
+
5
+ Harness Kit is a DeepSeek Harness plugin that gives AI work a repeatable engineering workflow: fixed
6
+ roles for analysis, design, implementation, review and testing; human approval gates; and a git
7
+ asset repository that keeps every round's output. **AI executes, humans gate, assets accumulate.**
8
+
9
+ Used alone, it is your project memory and a second pair of eyes. Used by a team, it is a shared
10
+ process and shared assets.
11
+
12
+ `7 roles` · `4 flow profiles` · `10 commands` · `zero runtime dependencies` · `local-first`
13
+
14
+ English | [简体中文](README.zh-CN.md)
15
+
16
+ > A harness is a set of restraints. The stronger the model, the more it needs a stable process
17
+ > instead of reinventing the approach on every task.
18
+
19
+ ---
20
+
21
+ ## It makes your project legible to AI first
22
+
23
+ Harness Kit is not only a workflow. After the workspace is created, **Start initialization
24
+ orchestration** probes the registered source repositories and fills in the project knowledge AI
25
+ would otherwise rediscover every time:
26
+
27
+ - a root `AGENTS.md` and a one-line `CLAUDE.md` pointer
28
+ - per-repository `CLAUDE.md` (stack, module entry points) and `docs/CODE_STANDARDS.md` (coding rules)
29
+ - `<repo>/.harness/build.json`: build, start and test commands
30
+ - `codebase-guide/`: module docs loaded on demand instead of into every prompt
31
+ - per-repository `.codegraph/`: class, method and call-chain indexes the AI can query instead of reading everything
32
+ - `.harness/scripts`, `rules`, `templates`: board, health checks, spec lint and coding baselines
33
+
34
+ You confirm the plan before anything is written; existing files are skipped and `build.json` only
35
+ gains missing keys. If CodeGraph is not installed, the scripts try to install it, and you can skip it.
36
+
37
+ ---
38
+
39
+ ## Three steps in the UI (no commands to memorize)
40
+
41
+ ### 1. Open the sidebar and create a workspace
42
+
43
+ **Harness Kit → + Workspace → New workspace**:
44
+
45
+ - pick a local directory (it can be empty)
46
+ - choose the asset repository: local, a new git repository, or an existing team repository
47
+ - register source repositories (URL, role, branch), or add them later
48
+ - click **Create and initialize**
49
+
50
+ The wizard runs an **environment check** first: if `git` or `Python 3` is missing, it shows the
51
+ install command for your platform instead of failing after submission. Initialization runs in the
52
+ background, survives a page refresh, and reports back in the panel; then **Start initialization
53
+ orchestration** probes the repositories and generates the docs and indexes described above.
54
+
55
+ ![New workspace: directory, asset repository, source repositories and environment check](docs/assets/ui-onboarding.png)
56
+
57
+ ### 2. Click + to create a task
58
+
59
+ - choose **Requirement** or **Fix**
60
+ - write one sentence; the task name can stay empty and is generated from the description
61
+ - optionally attach a requirements file
62
+
63
+ Creating the task opens a dedicated session: requirement mode starts from the proposal, fix mode
64
+ starts from the defect document and the quality gate.
65
+
66
+ ![New task: requirement or fix shortcut, one sentence to start](docs/assets/ui-new-task.png)
67
+
68
+ ### 3. Work from the panel
69
+
70
+ - task cards move between **Planning / Implementing / To archive**
71
+ - **Needs you** lists pending approvals, archives, and sync problems
72
+ - **Continue session** jumps to the task session; after an approval, the host advances the next
73
+ phase automatically (set `autoAdvance: false` in `.harness/kit.json` to disable)
74
+ - archive finished work into the collapsible history board
75
+ - 🕘 team activity shows who archived what and when
76
+ - ⚙ configuration edits source branches, auto-sync and model mappings
77
+
78
+ ![War room: needs-you list, planning/implementing/to-archive lanes and history board](docs/assets/ui-war-room.png)
79
+
80
+ > Screenshots use a sample workspace (`acme-platform`), not real project data.
81
+
82
+ > **Approvals are written by a human; the panel only reminds.** Approval 1 is recorded in
83
+ > `proposal.md`, the quality-gate decision in `bugfix.md`. That is deliberate: it keeps approvals
84
+ > from becoming a button-click ritual.
85
+ >
86
+ > The panel covers daily work. Asset rebinding, deleting a source repository and batch operations
87
+ > stay in the commands below.
88
+
89
+ ---
90
+
91
+ ## How it differs from personal vibe coding
92
+
93
+ | | Personal vibe coding | Harness Kit |
94
+ |---|---|---|
95
+ | Context | Lives in one session and disappears | Files under `.harness/`, diffable, committable, handover-ready |
96
+ | Quality | Depends on the individual's review at that moment | Fixed roles + approval gates + tool guards |
97
+ | Collaboration | Separate sessions, synchronized by word of mouth | Task claims, parallel worktrees, a serial test-environment lease |
98
+ | Models | One model for everything | Role/stage routing; strong models only where they matter |
99
+ | Audit | Chat history | Artifacts + approval markers + git history |
100
+ | Best for | One-off, exploratory, quick | Work that needs stable quality, iteration and handover |
101
+
102
+ Vibe coding wins by "think and type". The price is deferred: rework, review, rebuilding context.
103
+ Harness Kit moves part of that cost earlier, into specs and gates. **A one-file change is slower;
104
+ iterative, cross-module work that you return to weeks later is faster.**
105
+
106
+ ---
107
+
108
+ ## Why it's worth it, even solo
109
+
110
+ None of this requires a team. For a solo developer, the harness addresses the you of three months
111
+ from now, on another machine, in a new session: the process keeps quality stable and the assets keep
112
+ you from re-explaining.
113
+
114
+ ### Review cost: a second pair of eyes
115
+
116
+ The faster AI writes, the more there is to check. Fixed roles make CR and TE each do one job and
117
+ produce `code-review.md` and `test-report.md`, so review has an object and a conclusion instead of a
118
+ glance that depends on the day.
119
+
120
+ ### Handover: the next person may be future you
121
+
122
+ Context lives in `proposal.md`, `requirements.md` and `design.md`, not in a session. Come back a
123
+ month later, or hand the task to someone else, and reading the files is enough.
124
+
125
+ ### Consistency: not dependent on today's state
126
+
127
+ Four flow profiles and fixed approval points make "how we work" repeatable instead of a personal
128
+ habit. Roles and flows are plain files, overridable per project in `.harness/agents/` and
129
+ `.harness/flows/`.
130
+
131
+ ### Parallel: several tasks without collisions
132
+
133
+ Task claims, pooled worktrees and a serial test-environment lease address the three collisions that
134
+ appear when several tasks run at once: duplicate work, branch pollution, and fighting over the test
135
+ environment.
136
+
137
+ ### Model cost: spend where it matters
138
+
139
+ Use strong models for design and difficult review, fast models for routine work. The mapping lives
140
+ in `.harness/kit.json` and is not tied to one provider.
141
+
142
+ ### Assets compound, especially solo
143
+
144
+ Every round settles specs and memory entries into the asset repository: this round's lessons, last
145
+ month's specification. **The longer you use it, the thicker your assets, and the less each new task
146
+ starts from zero.** Templates and rules live under `.harness/` too, ready to adapt and commit.
147
+
148
+ ### Data and security
149
+
150
+ The plugin runs locally with zero runtime dependencies and no install scripts, and collects no
151
+ telemetry. Project assets live in your own git repository (your team's when shared); model requests
152
+ go only to the provider you configure.
153
+
154
+ ---
155
+
156
+ ## How it works
157
+
158
+ ### Seven roles
159
+
160
+ | Role | Owns | Artifact |
161
+ |---|---|---|
162
+ | Project Manager | The session Lead: orchestration, review, approvals, board | `proposal.md`, board |
163
+ | Business Analyst | Requirement clarification and acceptance criteria | `requirements.md` |
164
+ | Solution Architect | Technical design and blast radius | `design.md` |
165
+ | Readiness Reviewer | Readiness review with PASS / BLOCK | `readiness-report.md` |
166
+ | Developer | TDD implementation and self-test | Code, `dev-log.md` |
167
+ | Code Reviewer | Code review with PASS / send-back | `code-review.md` |
168
+ | Test Engineer | Build, unit tests, critical-path verification | `test-report.md` |
169
+
170
+ ### Four flow profiles
171
+
172
+ | Flow | Use | Path |
173
+ |---|---|---|
174
+ | `standard` | New features, cross-module work | BA → SA → RR → approval 1 → Dev → CR → TE → approval 2 |
175
+ | `quick` | Small changes | BA → SA (self readiness) → approval 1 → Dev → CR → TE → approval 2 |
176
+ | `bugfix` | Defect fixes, full flow | BA (`bugfix.md`) → approval 1 → Dev → CR → TE → approval 2 |
177
+ | `refactor` | Refactoring, cross-module | SA blast radius → BA → SA → RR → approval 1 → Dev → CR → TE → approval 2 |
178
+ | `fix` shortcut | Lightweight fixes | Quality gate → Dev → (`--full` adds CR/TE; `--light` verifies only) → archive |
179
+
180
+ ### Approval points and guards
181
+
182
+ - Approval 1: the plan is ready; a human decides whether to start implementation
183
+ - Quality gate: for the `fix` shortcut a human chooses "light" or `--full`
184
+ - Approval 2: implementation and testing are done; a human decides whether to archive
185
+ - Guards: source writes are blocked until the quality gate is recorded; destructive git commands
186
+ (`reset --hard`, `clean -f`, `push --force`) are rejected
187
+
188
+ ### The asset repository
189
+
190
+ `.harness/` is the working copy of the asset repository:
191
+
192
+ ```
193
+ .harness/
194
+ ├── kit.json # sources, model mapping, asset repository binding
195
+ ├── deliverables/ # per-round artifacts + _archive/
196
+ ├── specs/ # capability specs, appended per round
197
+ ├── memory/ # lessons, one file per entry
198
+ ├── tasks/ # board + machine-local state (sessions, claims, worktrees, test lease)
199
+ ├── agents/ flows/ # project-level role and flow overrides
200
+ └── scripts/ rules/ # refreshed with the plugin, not committed
201
+ ```
202
+
203
+ ### Parallelism and model routing
204
+
205
+ - Pooled worktrees: concurrent tasks reuse a worktree slot per repository instead of fighting over
206
+ one branch
207
+ - Test-environment lease: `/hk-te` keeps one task at a time on the single test environment
208
+ - Model routing: `kit.json` maps logical names (`reasoning`, `coding`, `fast`, or a role name) to a
209
+ concrete provider/model; unmapped names fall back to the session default
210
+
211
+ ---
212
+
213
+ ## Command reference (advanced)
214
+
215
+ | Command | What it does |
216
+ |---|---|
217
+ | `/hk-setup [--add <git-url>]` | Register source repositories in `kit.json`, cloning missing ones |
218
+ | `/hk-init [--assets <url\|init\|local>]` | Initialize or refresh `.harness/`, bind the asset repository |
219
+ | `/hk-new [<task>] <description> [--file <path>]` | Start a full-flow task |
220
+ | `/hk-propose <task>` | Run the propose phase |
221
+ | `/hk-apply <task> [feedback]` | Run the apply phase |
222
+ | `/hk-archive <task>` | Archive the round and run Spec/Memory merge |
223
+ | `/hk-fix [<task>] <description> [--full\|--light]` | Run the lightweight fix path |
224
+ | `/hk-te [acquire\|release <task> \| status]` | Serial test-environment lease |
225
+ | `/hk-sync` | Sync the asset repository (commit → rebase → append merge → push) |
226
+ | `/hk-doctor` | Check workspace health: kit, roles, rules, flows, scripts, board, model mappings |
227
+
228
+ ---
229
+
230
+ ## Install
231
+
232
+ ### In the app (recommended)
233
+
234
+ **Plugins → Add plugin**, then enter:
235
+
236
+ ```
237
+ dsh-harness-kit@0.1.0
238
+ ```
239
+
240
+ Enable the bundle after installation.
241
+
242
+ ### Command line
243
+
244
+ ```sh
245
+ dsh plugin --profile desktop add dsh-harness-kit@0.1.0
246
+ ```
247
+
248
+ Quit DSH Desktop first; replace `desktop` with your profile name for other profiles.
249
+
250
+ ### From a checkout
251
+
252
+ ```sh
253
+ dsh plugin --profile desktop add /absolute/path/HarnessKit
254
+ ```
255
+
256
+ ### Requirements
257
+
258
+ - DeepSeek Harness 0.2.x with the Web client (Desktop or `dsh web`)
259
+ - `git` and `Python 3` (the wizard checks both and shows install commands)
260
+ - A DSH session working directory to use as the Harness workspace
261
+
262
+ ---
263
+
264
+ ## Compatibility and known limits
265
+
266
+ - Declared DSH range: `>=0.2.0 <0.3.0`. DSH 0.3 will need a new plugin release.
267
+ - The panel is a Web client feature; commands and guards work in any profile with the Host plugin.
268
+ - The bundled `ai-coding` pack and the panel text are Chinese-first. Roles and flows are plain
269
+ files and can be overridden per project.
270
+ - No MCP host support yet (Claude Code, WorkBuddy): this release targets DSH only.
271
+ - The panel does not write approvals and does not rebind asset repositories; those stay in the
272
+ session commands.
273
+
274
+ ---
275
+
276
+ ## FAQ
277
+
278
+ **Is it slower than just asking AI to write?**
279
+ A one-file change: yes. Iterative, cross-module work that you return to weeks later: no. It moves
280
+ rework and handover cost earlier instead of removing them.
281
+
282
+ **Is it worth it for a solo developer?**
283
+ Yes. Solo work loses context and rhythm most easily: the harness keeps each round's specs, lessons
284
+ and decisions in files, so the next session does not start from zero. The CR/TE roles act as a fixed
285
+ second pass, and the generated `CLAUDE.md`, `build.json` and CodeGraph index save the AI from
286
+ re-reading the project every time.
287
+
288
+ **Do I have to use the full flow?**
289
+ No. Four profiles plus the `/hk-fix` shortcut; start with the light one.
290
+
291
+ **How does sharing work?**
292
+ The asset repository is git. Each person has a local workspace whose `.harness/` binds to the same
293
+ repository; sync through `/hk-sync` or git. Solo, local mode is enough: binding git is for moving
294
+ machines, backup and later sharing.
295
+
296
+ **Where does data go?**
297
+ Project assets stay in your local `.harness/` and your git (your team's when shared). The plugin
298
+ collects no telemetry; model requests go only to the provider you configure.
299
+
300
+ **Which hosts are supported?**
301
+ DeepSeek Harness only for now. MCP hosts are not implemented, and this document does not claim they
302
+ are.
303
+
304
+ ---
305
+
306
+ ## Development
307
+
308
+ ```sh
309
+ npm test # mock-agent regression suite
310
+ npm run pack:check # pack the tarball and verify its contents
311
+ ```
312
+
313
+ Client and panel changes still need a manual check in the real Web GUI.
314
+
315
+ ## Contributing
316
+
317
+ - Issues: https://github.com/LaoLiang-agent/HarnessKit/issues
318
+ - Release and maintenance runbook: [docs/PUBLISHING.md](docs/PUBLISHING.md)
319
+
320
+ ## License
321
+
322
+ MIT © 2026 leo. See [LICENSE](LICENSE).
@@ -0,0 +1,278 @@
1
+ # Harness Kit
2
+
3
+ **把 AI 编程从个人手感,变成团队流程。**
4
+
5
+ Harness Kit 是 DeepSeek Harness 的多 Agent 工程流程插件:它把方案、开发、评审、测试拆给固定角色,在关键节点让人做审批,并把每一轮产物沉淀进你自己的 git 资产仓库。**AI 负责执行,人负责把关,资产持续沉淀。**
6
+
7
+ 一个人用,它是你的项目记忆和第二双眼睛;一个团队用,它是共享的流程和资产。
8
+
9
+ `7 个角色` · `4 档流程` · `10 个命令` · `零运行时依赖` · `数据留在本地`
10
+
11
+ [English](README.md) | 简体中文
12
+
13
+ > Harness 是"挽具":模型越强,越需要一套约束让它稳定输出,而不是每次都重新即兴发挥。
14
+
15
+ ---
16
+
17
+ ## 它先帮你把项目变成 AI 能读懂的样子
18
+
19
+ Harness Kit 不只是"加流程"。创建完成后点「启动初始化编排」,它会探测已登记的子工程,把 AI 每次都要重新摸索的项目知识补齐:
20
+
21
+ - 根目录 `AGENTS.md`,以及一行指针 `CLAUDE.md`
22
+ - 每个子工程的 `CLAUDE.md`(技术栈、模块入口)和 `docs/CODE_STANDARDS.md`(编码规范)
23
+ - `<子工程>/.harness/build.json`:编译、启动、测试命令
24
+ - `codebase-guide/`:模块级文档,按需加载,不占上下文
25
+ - 每个子工程的 `.codegraph/`:类、方法、调用链索引,AI 直接查,不必全量读代码
26
+ - `.harness/scripts`、`rules`、`templates`:看板、体检、规格校验与编码底线
27
+
28
+ 生成前先给你一份计划确认;已存在的文件跳过,`build.json` 只补缺失键、不覆盖已有值。本机没有 CodeGraph 工具时脚本会尝试安装,也可以跳过。
29
+
30
+ ---
31
+
32
+ ## 三步上手(不用记命令)
33
+
34
+ ### 1. 打开侧栏,新建工作区
35
+
36
+ 侧栏打开 **Harness Kit** → 「+ 工作区」→「新建工作区」:
37
+
38
+ - 选一个本地目录(可以是空目录)
39
+ - 选资产仓库:本地模式 / 新建 git 仓库 / 绑定团队 git 仓库
40
+ - 登记子工程(仓库地址、角色、分支),也可以稍后添加
41
+ - 点「创建并初始化」
42
+
43
+ 向导会先做**环境检查**:缺 `git` 或 `Python 3` 时直接给出对应平台的安装命令,不用提交后才发现失败。初始化在后台执行,刷新页面不会中断,完成后面板给出报告;点「启动初始化编排」即可探测子工程并生成文档/索引(见上一节)。
44
+
45
+ ![新建工作区:目录、资产仓库、子工程与环境检查](docs/assets/ui-onboarding.png)
46
+
47
+ ### 2. 点「+」立项
48
+
49
+ - 选「需求」或「fix 直通」
50
+ - 写一句话描述;任务名可以留空,自动生成英文短名
51
+ - 可选附一份需求文件
52
+
53
+ 点「立项」后会自动打开一个**专属会话**开始执行:需求模式从 proposal 起草开始,fix 模式从缺陷文档与质量门开始。
54
+
55
+ ![新建任务:需求或 fix 直通,一句话描述即可立项](docs/assets/ui-new-task.png)
56
+
57
+ ### 3. 回到面板推进
58
+
59
+ - 任务卡片在「规划中 / 实施中 / 待归档」三列之间移动
60
+ - 「需要你」列出等你处理的事:审批、待归档、同步落后或冲突
61
+ - 点「继续会话」直达对应会话;处理完审批后自动接续下一阶段(默认开启,可在 `.harness/kit.json` 设 `autoAdvance: false` 关闭)
62
+ - 完成后归档,卡片进入底部「历史任务板」
63
+ - 🕘 看团队动态:谁在什么时候归档了什么
64
+ - ⚙ 配置:子工程基线分支、自动同步、模型映射
65
+
66
+ ![作战室:需要你、规划/实施/待归档三列与历史任务板](docs/assets/ui-war-room.png)
67
+
68
+ > 截图使用示例工作区(`acme-platform`),不是真实项目数据。
69
+
70
+ > **审批由人写下,面板只提醒、不代写**——审批 1 写进 `proposal.md`,质量门裁决写进 `bugfix.md`。这是刻意设计,防止审批流于形式。
71
+ >
72
+ > 面板覆盖日常操作;资产换绑、删除子工程、批量执行仍走命令(见下方速查)。
73
+
74
+ ---
75
+
76
+ ## 它和"个人 Vibe Coding"有什么不同
77
+
78
+ | 维度 | 个人 Vibe Coding | Harness Kit |
79
+ |---|---|---|
80
+ | 上下文 | 留在会话里,关掉就散 | 落进 `.harness/`,可 diff、可提交、可交接 |
81
+ | 质量 | 靠个人当时的审查状态 | 固定角色 + 审批点 + 工具护栏 |
82
+ | 协作 | 各开各的会话,靠口头同步 | 任务认领、并行 worktree、测试环境租约 |
83
+ | 模型 | 一个模型从头用到尾 | 角色/阶段级路由,强模型只用在关键处 |
84
+ | 审计 | 聊天记录 | 产物 + 审批标记 + git 历史 |
85
+ | 适用 | 一次性、探索性、短平快 | 需要稳定质量、反复迭代、可交接 |
86
+
87
+ Vibe Coding 的优势是"想到就写",代价是把成本推给未来:返工、审查、上下文重建。Harness Kit 把一部分成本提前到规格和门禁上——**单文件小改会更慢,需要反复迭代、跨模块、隔一段时间再回来接手的活会更快。**
88
+
89
+ ---
90
+
91
+ ## 为什么值得用,哪怕只有你一个人
92
+
93
+ 下面这些不要求你先有一个团队。一个人开发时,harness 解决的是"三个月后的你"、"换一台机器的你"、"下一次会话的你":流程保证稳定,资产沉淀保证不用重讲。
94
+
95
+ ### 审查成本:给自己第二双眼睛
96
+
97
+ AI 写得越快,需要看的越多。固定角色让 CR/TE 各自只做一件事,产出 `code-review.md`、`test-report.md`,审查有对象、有结论,而不是凭当天状态扫一眼。
98
+
99
+ ### 交接成本:交接对象也可能是未来的你
100
+
101
+ 上下文不在会话里,而在 `proposal.md`、`requirements.md`、`design.md` 里。隔一个月回来,或换一个人接手,读文件就能继续,不需要重新讲一遍背景。
102
+
103
+ ### 一致性:不取决于当天的状态
104
+
105
+ 四档流程 + 固定审批点,让"怎么做"成为可重复的流程,而不是个人习惯。角色和流程都是纯文件,项目可以在 `.harness/agents/`、`.harness/flows/` 里覆写。
106
+
107
+ ### 并行:同时推进多个任务也不互相踩
108
+
109
+ 看板认领、池化 worktree、测试环境串行租约,解决多个任务同时跑时最容易出的三类冲突:重复做、分支互相污染、抢测试环境。
110
+
111
+ ### 模型成本:好钢用在刀刃上
112
+
113
+ 方案和难审代码用强模型,样板任务用快模型;映射写在 `.harness/kit.json`,不绑死某个 provider。
114
+
115
+ ### 资产沉淀:一个人用尤其明显
116
+
117
+ 每跑完一轮,`specs/` 与 `memory/` 都会沉淀进资产仓库:这次的踩坑、上次的规格。**用得越久,资产越厚,下一次从零解释的成本越低。** 模板和规则也在 `.harness/` 里,可以按自己的习惯改写并提交。
118
+
119
+ ### 数据与安全
120
+
121
+ 插件本地运行,零运行时依赖、无安装脚本、不收集遥测;项目资产在你自己的 git 仓库里(共享时就是团队仓库);模型请求只发往你配置的 provider。
122
+
123
+ ---
124
+
125
+ ## 它怎么工作
126
+
127
+ ### 七个角色
128
+
129
+ | 角色 | 负责 | 典型产出 |
130
+ |---|---|---|
131
+ | Project Manager | 由当前会话 Lead 承担:编排、复核、推进审批与看板 | `proposal.md`、看板 |
132
+ | Business Analyst | 需求澄清与验收标准 | `requirements.md` |
133
+ | Solution Architect | 技术方案与影响面分析 | `design.md` |
134
+ | Readiness Reviewer | 方案就绪评审,给出 PASS / BLOCK | `readiness-report.md` |
135
+ | Developer | TDD 实施与自测 | 代码、`dev-log.md` |
136
+ | Code Reviewer | 代码审查,给出 PASS / 打回 | `code-review.md` |
137
+ | Test Engineer | 构建、单测、关键路径验证 | `test-report.md` |
138
+
139
+ ### 四档流程
140
+
141
+ | 流程 | 适用 | 路径 |
142
+ |---|---|---|
143
+ | `standard` | 新功能、跨模块 | BA → SA → RR → 审批 1 → Dev → CR → TE → 审批 2 |
144
+ | `quick` | 小改动 | BA → SA(就绪自评)→ 审批 1 → Dev → CR → TE → 审批 2 |
145
+ | `bugfix` | 缺陷修复(全流程) | BA(`bugfix.md`)→ 审批 1 → Dev → CR → TE → 审批 2 |
146
+ | `refactor` | 重构、跨模块 | SA 影响面 → BA → SA → RR → 审批 1 → Dev → CR → TE → 审批 2 |
147
+ | `fix` 直通 | 轻量修复 | 质量门 → Dev →(`--full` 含 CR/TE;`--light` 只验证)→ 归档 |
148
+
149
+ ### 审批点与护栏
150
+
151
+ - 审批 1:方案阶段结束,人决定是否进入开发
152
+ - 质量门:fix 直通由人裁决「轻量」或「--full」
153
+ - 审批 2:实施与测试结束,人决定是否归档
154
+ - 护栏:质量门未裁决时禁止写源码区;破坏性 git 命令(`reset --hard`、`clean -f`、`push --force`)直接拦截
155
+
156
+ ### 资产仓库
157
+
158
+ `.harness/` 就是资产仓库的工作副本:
159
+
160
+ ```
161
+ .harness/
162
+ ├── kit.json # 子工程、模型映射、资产仓库绑定
163
+ ├── deliverables/ # 每轮交付物 + _archive/
164
+ ├── specs/ # 能力规格,按轮次追加
165
+ ├── memory/ # 踩坑记忆,一人一文件
166
+ ├── tasks/ # 看板 + 本机状态(会话绑定、认领、worktree、测试环境租约)
167
+ ├── agents/ flows/ # 项目级角色/流程覆写
168
+ └── scripts/ rules/ # 随插件版本刷新,不入资产仓库
169
+ ```
170
+
171
+ ### 并行与模型路由
172
+
173
+ - 池化 worktree:多个任务同时开发时,按仓库分配复用工作区,避免分支互相污染
174
+ - 测试环境租约:`/hk-te` 保证同一时间只有一个任务占用测试环境
175
+ - 模型路由:`kit.json` 把逻辑名(`reasoning` / `coding` / `fast` 或角色名)映射到具体 provider/model,未映射时回退会话默认
176
+
177
+ ---
178
+
179
+ ## 命令速查(进阶)
180
+
181
+ | 命令 | 作用 |
182
+ |---|---|
183
+ | `/hk-setup [--add <git-url>]` | 登记代码仓库到 `kit.json`,缺少的自动 clone |
184
+ | `/hk-init [--assets <url\|init\|local>]` | 初始化/刷新 `.harness/`,绑定资产仓库 |
185
+ | `/hk-new [<任务>] <描述> [--file <路径>]` | 启动全流程任务 |
186
+ | `/hk-propose <任务>` | 执行方案阶段 |
187
+ | `/hk-apply <任务> [反馈]` | 执行实施阶段 |
188
+ | `/hk-archive <任务>` | 归档本轮产物,执行 Spec/Memory Merge |
189
+ | `/hk-fix [<任务>] <描述> [--full\|--light]` | 轻量修复直通 |
190
+ | `/hk-te [acquire\|release <任务> \| status]` | 测试环境串行租约 |
191
+ | `/hk-sync` | 资产仓库同步(提交 → rebase → 追加合并 → push) |
192
+ | `/hk-doctor` | 工作区体检:kit、角色、规则、流程、脚本、看板、模型映射 |
193
+
194
+ ---
195
+
196
+ ## 安装
197
+
198
+ ### 应用内(推荐)
199
+
200
+ **Plugins → Add plugin**,输入:
201
+
202
+ ```
203
+ dsh-harness-kit@0.1.0
204
+ ```
205
+
206
+ 安装后启用 bundle。
207
+
208
+ ### 命令行
209
+
210
+ ```sh
211
+ dsh plugin --profile desktop add dsh-harness-kit@0.1.0
212
+ ```
213
+
214
+ 需要先完全退出 DSH Desktop;其他 profile 把 `desktop` 换成实际名称。
215
+
216
+ ### 从源码
217
+
218
+ ```sh
219
+ dsh plugin --profile desktop add /绝对路径/HarnessKit
220
+ ```
221
+
222
+ ### 要求
223
+
224
+ - DeepSeek Harness 0.2.x,带 Web 客户端(Desktop 或 `dsh web`)
225
+ - `git` 与 `Python 3`(向导会检查并给出安装命令)
226
+ - 一个 DSH 会话工作目录,作为 Harness 工作区
227
+
228
+ ---
229
+
230
+ ## 兼容性与已知限制
231
+
232
+ - 声明 DSH 范围 `>=0.2.0 <0.3.0`;DSH 0.3 发布后需要新的插件版本
233
+ - 面板是 Web 端功能;命令与护栏在加载 Host 插件的 profile 中可用
234
+ - 内置 `ai-coding` 内容包与面板文案以中文为主;角色/流程是纯文件,可按项目覆写
235
+ - 暂不支持 MCP 宿主(Claude Code / WorkBuddy 等),当前聚焦 DSH
236
+ - 面板不代写审批、不做资产换绑;这些操作保留在会话命令里
237
+
238
+ ---
239
+
240
+ ## FAQ
241
+
242
+ **会不会比直接让 AI 写更慢?**
243
+ 单文件小改会;需要反复迭代、跨模块、隔一段时间再回来接手的活不会。它把返工和交接成本提前,而不是消灭。
244
+
245
+ **一个人有必要用吗?**
246
+ 有。一个人最容易丢的是上下文和节奏:harness 把每轮的规格、踩坑和决策留在文件里,下次不用重新解释;CR/TE 角色相当于固定的第二遍审查;初始化补齐的 `CLAUDE.md`、`build.json`、`CodeGraph` 让 AI 不必每次重读整个项目。
247
+
248
+ **必须走完整流程吗?**
249
+ 不用。四档流程 + `/hk-fix` 直通,可以先只用轻量档;流程档位在立项时确定。
250
+
251
+ **怎么共享?**
252
+ 资产仓库就是 git。每个人在自己机器上有独立工作区,`.harness/` 绑定同一个资产仓库,靠 `/hk-sync` 或 git 同步。一个人用本地模式即可,绑定 git 是为了换机、备份和以后共享。
253
+
254
+ **数据去哪?**
255
+ 项目资产在本地 `.harness/` 和你的 git(共享时就是团队仓库);插件不收集、不上传遥测;模型请求只发往你配置的 provider。
256
+
257
+ **支持哪些宿主?**
258
+ 当前只支持 DeepSeek Harness。MCP 宿主(Claude Code 等)尚未实现,文档不会假装支持。
259
+
260
+ ---
261
+
262
+ ## 开发
263
+
264
+ ```sh
265
+ npm test # mock agent 回归套件
266
+ npm run pack:check # 打包并校验发布内容
267
+ ```
268
+
269
+ Client 与面板改动仍需在真实 Web GUI 里手动验证。
270
+
271
+ ## 参与与反馈
272
+
273
+ - 问题与建议:https://github.com/LaoLiang-agent/HarnessKit/issues
274
+ - 发布与维护流程见 [docs/PUBLISHING.md](docs/PUBLISHING.md)
275
+
276
+ ## License
277
+
278
+ MIT © 2026 leo,见 [LICENSE](LICENSE)。