@haaaiawd/skeinn 0.0.0-stage → 2.5.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/CHANGELOG.md +102 -0
- package/CONTRIBUTING.md +37 -0
- package/EVIL_EVAL.md +84 -0
- package/LICENSE +21 -0
- package/README.md +196 -2
- package/README.zh-CN.md +262 -0
- package/SECURITY.md +11 -0
- package/cli/bin/skeinn.js +512 -0
- package/cli/src/protocol.js +862 -0
- package/cli/src/store.js +1992 -0
- package/design.md +257 -0
- package/docs/PROMPT_CATALOG.md +139 -0
- package/docs/RELEASE_CHECKLIST.md +53 -0
- package/docs/UX_FLOW.md +200 -0
- package/docs/ai-development-landscape-2026-10.md +163 -0
- package/docs/brand/skeinn-mark-dark.svg +14 -0
- package/docs/brand/skeinn-mark.svg +14 -0
- package/docs/brand/skeinn-wordmark-dark.svg +11 -0
- package/docs/brand/skeinn-wordmark-light.svg +11 -0
- package/docs/eval/RELAY-001.md +115 -0
- package/docs/loom-eval-loop.drawio +21 -0
- package/docs/loom-eval-loop.svg +56 -0
- package/docs/loom-journey-audit.md +107 -0
- package/docs/loom-production-loop.drawio +41 -0
- package/docs/loom-production-loop.svg +92 -0
- package/package.json +54 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 2.5.0
|
|
4
|
+
|
|
5
|
+
- Redesigned Keeper around **two minimal primitives** (`reviewed_digests` per-artifact hash map + unified `scope`-pinned `findings` ledger) and exact topological horizon calculation (`activeHorizon(depth=2)`):
|
|
6
|
+
- **`passed_with_advisories`**: Minor-only items no longer force another full Keeper round; they pass Launch immediately and pin to their `TASK-ID` or `.skeinn/design/<doc>.md` scope.
|
|
7
|
+
- **Automatic `task start` surfacing & gating**: Starting any Task automatically surfaces all open findings pinned to that Task OR its `reads`/`implements` docs (blocking severity gates start until resolved via `skeinn keeper resolve <FND-ID> --evidence "<proof>"`; minor severity surfaces as an active advisory).
|
|
8
|
+
- **Scope-bounded Delta Re-check (Round 2+)**: Follow-up Keeper rounds automatically inject only `dirty` modified artifacts and open blocking findings rather than the full corpus, eliminating fresh-eyes nitpicking spirals.
|
|
9
|
+
- **Non-convergence (`>=`) ping-pong guard**: If blocking findings fail to strictly decrease across two consecutive rounds, `skeinn project ready` halts blind looping without dumping internal chores on the human (unlockable via `--force-round --reason`).
|
|
10
|
+
- **In-Flight Checkpoints & Late-Entering Horizon Review**: Launch pass is a one-time birth certificate (`launch_completed`); distant design docs entering the horizon or designs updated mid-flight via `decision` automatically appear as `dirty` for lightweight `skeinn keeper checkpoint prompt|record` and `skeinn context --checkpoint`.
|
|
11
|
+
- **Empirical Spike tasks (`kind: "spike"`)**: Can start in `shaping` before Launch without `implements` to resolve physical/empirical unknowns with real evidence. Delivery Tasks cannot `depends_on` a spike (enforced in `validateTasks`, covering both `task plan` and `task update`) — distill findings into Design/Capability or `skeinn record` instead.
|
|
12
|
+
- **Silent-drift watchdog**: Completing 5 delivery Tasks since the last clean review/checkpoint raises a warning in `skeinn check` and a watch line in `skeinn context` — derived purely from timestamps, no new state; `drift_detected` verdicts deliberately do not reset it, only `clean` does. Checkpoint prompt/context inject the recent delivery Tasks' `touches` so an empty `dirty` set never leaves the reviewer a blank page.
|
|
13
|
+
- **Relaunch escape hatch**: `skeinn keeper reset --reason <text>` clears `reviewed_digests` and logs a decision for genuine full-direction pivots.
|
|
14
|
+
|
|
15
|
+
## 2.4.0
|
|
16
|
+
|
|
17
|
+
- Upgraded Evil Eval (`skeinn eval scaffold`) to a 3-tier budget-aware pyramid (`probe` ¥2–5, default 3-baton zero-memory `relay` ~¥20, and `full`), adding per-baton prompts, `hidden-oracle.mjs`, `telemetry-template.json`, and Pairwise Forced-Choice (`X_CLEAR_WIN | TIE | Y_CLEAR_WIN`) blind judging.
|
|
18
|
+
- Renamed project, CLI binary, and state directory from LOOM/`.loom/` to Skeinn (`@haaaiawd/skeinn`, `skeinn`, `.skeinn/`), with a legacy `.loom/` migration guard and minimalist 3-element SVG brand assets.
|
|
19
|
+
- Redesigned Capability into a low-friction, high-substance single-file workflow (`.skeinn/capabilities/<slug>.md`): replaced the 4-command decision-tree ceremony (`add → research → synthesize → confirm` + `research/` folder) with one command (`skeinn capability add <slug> --title <field> [--mode external_researched|codebase_grounded|offline_reflection]`) and a natural three-part flow: **How real practitioners operate** (with verifiable external sources), **Reflection for this project**, and **Operational rules and Design delta** (Before → After).
|
|
20
|
+
- Closed anti-laziness loopholes at `skeinn project ready` and `skeinn check`: silent Capability omission is now rejected (projects must add 1–3 bottleneck capabilities or explicitly record `skeinn capability exempt --reason <text>`, which Keeper audits); `external_researched` capabilities reject `agent-authored` / self-authored filler and missing `Design delta`; offline runs must declare `Mode: offline_reflection` honestly and stay visibly marked.
|
|
21
|
+
- Upgraded core Design templates (`product`, `experience`, `system`, `contract`) with **Applied capabilities**, **Alternatives considered** (requiring at least two genuinely viable options, no strawmen), and **How this could look done yet fail**.
|
|
22
|
+
- Removed the mandatory per-Task `capability_hooks` ceremony tax and added lightweight `guardrails[]` injected directly into active Task context (legacy `capability_hooks` remain supported).
|
|
23
|
+
- Added **Anti-laziness audit** to the independent Keeper prompt (auditing unjustified exemptions, fake research, zero-delta capabilities, strawman Design options, and dropped guardrails).
|
|
24
|
+
- Fixed a latent bug in `startTask` dependency checking (`item.status === 'done'`) and added stale-downstream `needs_recheck` warnings in `skeinn check` when an upstream Task is reopened.
|
|
25
|
+
- Included `STRUCTURE.md` and `capability_exemption` in `projectDigest`.
|
|
26
|
+
|
|
27
|
+
## 2.3.0
|
|
28
|
+
|
|
29
|
+
- Clarification rounds: `skeinn clarify start --reason` pauses material work when the human changes direction; answers and new frontier questions (each carrying a persisted recommendation) record through `skeinn clarify resolve --json-file`, and `skeinn clarify close` refuses until every question is resolved or deliberately skipped — then cascades into `skeinn decision`, document updates, and Task impact warnings.
|
|
30
|
+
- Clarification guidance is wired into `skeinn --help`, `skeinn help clarify`, `skeinn clarify --help`, the runtime and execution protocols, the AGENTS.md anchor, and context recommendations; an open round becomes the top recommendation and lists current frontier questions with their recommendations.
|
|
31
|
+
- `skeinn context` is lean by default: it returns the state header, shaping state, PROJECT.md, STRUCTURE.md, and active Task context without re-injecting the ~190-line static protocol (~1.4k tokens saved per repeat call). `skeinn context --full` restores the complete protocol; lean output points first-entry and post-reset Agents at it, and `--keeper` always stays full.
|
|
32
|
+
- The capability quality bar (nodes need a source citation and a counterexample) is visible in the lean state block, not only in the full protocol.
|
|
33
|
+
|
|
34
|
+
## 2.2.0
|
|
35
|
+
|
|
36
|
+
- Shaping-path guidance: `skeinn --help` now states what each shaping step buys and what skipping costs, and names conceptual help topics.
|
|
37
|
+
- `skeinn help <concept>` (`shaping`, `design`, `capability`, `task`, `deliverable`) gives each artifact a short purpose-plus-pointer; bare subcommands like `skeinn capability` and `skeinn design --help` land on the same pointers instead of a usage error.
|
|
38
|
+
- Shaping commands return an additive `next` field chaining the lifecycle: init → record → capability add/research/synthesize/confirm → design add → deliverable → task plan → project ready; `skeinn task start` points back at `skeinn context`.
|
|
39
|
+
- `skeinn context` during shaping names the actual unfinished frontier — template PROJECT.md, missing or templated design documents, capability lifecycle states, open high-impact questions, empty Work Map — instead of a generic keep-shaping sentence.
|
|
40
|
+
- Capabilities now precede design in every guided path: dossier decision trees produce the design decisions, so design documents are written informed by confirmed dossiers.
|
|
41
|
+
- `skeinn init` output lists the `AGENTS.md` anchor it installs (omitted correctly in sidecar mode).
|
|
42
|
+
|
|
43
|
+
## 2.1.3
|
|
44
|
+
|
|
45
|
+
- Removed Keeper auto-pass: every still-open finding must be closed with evidence in a later independently attested pass. A changed project digest proves a change, not that findings were resolved.
|
|
46
|
+
- `skeinn task start` now requires an independently attested Keeper pass (`review.mode: "independent"`) or a recorded `skeinn keeper skip`; `skeinn check` reports an unattested legacy pass as an error instead of a quiet warning.
|
|
47
|
+
- Keeper findings are cumulative across attempts: a passing record must carry `closure_results` for every gap still open from earlier rounds.
|
|
48
|
+
- Task references are verified, not just non-empty: `implements` must resolve to an existing design file and section (or a decision name present in project truth), and `capability_hooks` must resolve to an existing dossier and node. `skeinn project ready` runs this integrity check.
|
|
49
|
+
- `skeinn context` lists each blocked Task with its reason and recovery conditions, and recommends `skeinn task reopen <id> --reason` when nothing is executable.
|
|
50
|
+
- Done Tasks resist silent rewrites: `skeinn task update` on a done Task is rejected with a reopen pointer, and reopening a blocked Task requires a concrete reason describing how the recovery conditions were met.
|
|
51
|
+
- Decision-affected done Tasks warn only until re-verified: reopening and re-completing the Task after the decision clears the warning.
|
|
52
|
+
- Deliverable coverage now distinguishes planned from delivered: units covered only by open or blocked Tasks no longer count as delivered.
|
|
53
|
+
- `skeinn record --help` documents `resolved` and `retire_assumptions` so Agents can close questions and assumptions they opened.
|
|
54
|
+
- Planning new Tasks on a completed project returns status to `building`; `skeinn context` no longer claims "all done" while new Tasks are open.
|
|
55
|
+
|
|
56
|
+
## 2.1.2
|
|
57
|
+
|
|
58
|
+
- Added environment-aware clarification through `skeinn context --human-channel available|unavailable`. Unattended Agents inspect first, research only permitted objective facts, and then use bounded assumptions or blocks rather than fabricating users or substituting web search for intent.
|
|
59
|
+
- Added `--state-dir <outside-workspace-dir>` sidecars for isolated benchmark and sandbox runs. Sidecars preserve virtual `.skeinn/` Task references without mutating the scored workspace or its `AGENTS.md`.
|
|
60
|
+
- Added equal human-channel controls and unattended condition prompts to Evil Eval scaffolding.
|
|
61
|
+
- Added explicit capability authority provenance: human selections become confirmed, while Agent selections remain visibly provisional until human confirmation.
|
|
62
|
+
- Required independent Keeper review provenance for a passing handoff; known self-review can no longer be recorded as an independent pass.
|
|
63
|
+
- Added Task integrity enforcement for design links, capability hooks or explicit exemptions, plus declared output existence checks before completion.
|
|
64
|
+
- Added command-specific canonical JSON help and recovery pointers for every structured-write command.
|
|
65
|
+
- Updated generated Agent guidance and both public READMEs so installed and source-checkout invocation paths are unambiguous.
|
|
66
|
+
|
|
67
|
+
## 2.1.1
|
|
68
|
+
|
|
69
|
+
- Re-published 2.1.0 content with corrected CHANGELOG line endings.
|
|
70
|
+
|
|
71
|
+
## 2.1.0
|
|
72
|
+
|
|
73
|
+
- Added a current-state and recommended-action header to `skeinn context` output. Agents entering a project or resuming after compression now see project status, active task, work-map counts, and a recommended next action before the full protocol. The recommendation is advisory, not a script.
|
|
74
|
+
- Rewrote `AGENTS.md` with explicit Skeinn trigger conditions (project entry, context reset, before substantial work, between Tasks) and a standard work rhythm that keeps Agent judgment while making the next step obvious.
|
|
75
|
+
- Integrated Crux integrity-chain review into the Keeper handoff. The Keeper now checks that responsible intent, project promises, design and capability decisions, Work Map, executable behavior, and human feedback loop form an intact chain, and looks for omission, substitution, drift, unsupported leaps, blindness, and ownerless gaps.
|
|
76
|
+
- Added staged visibility and review guidance to the project template and active-Task execution protocol. Tasks should prefer human-visible acceptance evidence, the Agent should show real working things at milestones, run `skeinn check` and project tests together before declaring a batch done, and prioritize reaching an exciting surface early to sustain the human's momentum.
|
|
77
|
+
- Strengthened capability source validation: `skeinn capability synthesize` now requires each decision-tree node's `source:` citation to reference a real `.md` file in the dossier's `research/` directory.
|
|
78
|
+
- Added `research/_guide.md` generation in `skeinn capability research` so Agents know what good research material looks like, what to avoid, and how to cite sources.
|
|
79
|
+
- Added `.skeinn/STRUCTURE.md` as a fifth project-truth layer declaring where source code, tests, docs, assets, and configuration files live. `skeinn check` warns when it is missing or still templated.
|
|
80
|
+
- Added `skeinn decision --json-file` for recording consequential superseding decisions with affected files and tasks. `skeinn check` warns when a done Task is marked affected by a later decision.
|
|
81
|
+
- Added `acceptance[]` as the primary Task completion structure, pairing `criterion`, `verify_by`, and `evidence`. Legacy `done_when[]` remains supported.
|
|
82
|
+
- Added Keeper auto-pass: when all Keeper gaps are minor and 3 or fewer, fixing them and running `skeinn project ready` auto-passes without another Keeper round. (removed in 2.1.3)
|
|
83
|
+
- Added deliverable coverage tracking through `skeinn deliverable add` and Task `covers` field. `skeinn check` reports uncovered delivery units.
|
|
84
|
+
- Added `skeinn capability research → synthesize → confirm` lifecycle with status tracking per dossier.
|
|
85
|
+
- Updated help text with a typical first-pass flow and capability lifecycle sequence.
|
|
86
|
+
|
|
87
|
+
## 2.0.1
|
|
88
|
+
|
|
89
|
+
- Added an active-Task execution protocol that restores workspace-aware coding guidance, risk-based testing, restartable progress, criterion-level proof, and conditional commit/PR boundaries after context resets.
|
|
90
|
+
- Strengthened the generated `AGENTS.md` anchor so Agents reload Skeinn at project entry, after context loss, and before resumed editing without invoking it before every tool call.
|
|
91
|
+
|
|
92
|
+
## 2.0.0
|
|
93
|
+
|
|
94
|
+
- Rebuilt Skeinn as invisible Agent infrastructure around project understanding, a scalable design-document graph, separate professional-field dossiers, a broad Work Map, and one active Task.
|
|
95
|
+
- Replaced fixed roles and stages with an adaptive clarification protocol and explicit convergence conditions.
|
|
96
|
+
- Added human-editable project truth, structured continuity state, and superseding decision history.
|
|
97
|
+
- Added context selection that keeps very large Task maps on disk and injects only the active horizon.
|
|
98
|
+
- Added seven adaptable design-document templates and `skeinn prompts` as a complete live prompt inventory.
|
|
99
|
+
- Reduced Keeper to one independent build-readiness handoff with revision, changed-digest, fresh-run, and stale-state enforcement.
|
|
100
|
+
- Added controlled Evil Eval scaffolding for equal-condition, repeated, reset-heavy blind comparison.
|
|
101
|
+
- Added bilingual English/Chinese release documentation and a flat, minimal visual system with editable loop diagrams.
|
|
102
|
+
- Deliberately stopped automatic mutation of legacy `.skeinn/v1` projects.
|
package/CONTRIBUTING.md
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Contributing to Skeinn
|
|
2
|
+
|
|
3
|
+
Skeinn should become simpler when it changes. A contribution is strongest when it preserves the natural
|
|
4
|
+
human–Agent conversation, keeps project truth inspectable on disk, and proves its effect without adding
|
|
5
|
+
another ritual.
|
|
6
|
+
|
|
7
|
+
## Before changing code
|
|
8
|
+
|
|
9
|
+
1. Read [the system design](design.md) and [the UX loop](docs/UX_FLOW.md).
|
|
10
|
+
2. Run the current suite and CLI locally:
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
npm test
|
|
14
|
+
node cli/bin/skeinn.js --help
|
|
15
|
+
node cli/bin/skeinn.js prompts
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
3. Keep a change inside one observable problem. If a contract or stored shape changes, update its design,
|
|
19
|
+
prompt, help text, and tests together.
|
|
20
|
+
|
|
21
|
+
## Pull requests
|
|
22
|
+
|
|
23
|
+
A useful pull request explains:
|
|
24
|
+
|
|
25
|
+
- the user or Agent failure it fixes;
|
|
26
|
+
- the smallest complete change that fixes it;
|
|
27
|
+
- the exact command or artifact that proves the result;
|
|
28
|
+
- any compatibility, migration, or unverified boundary.
|
|
29
|
+
|
|
30
|
+
Prompt changes must remain visible through `skeinn prompts` and be reflected in
|
|
31
|
+
[`docs/PROMPT_CATALOG.md`](docs/PROMPT_CATALOG.md). Changes that claim better quality need a baseline-relative
|
|
32
|
+
proof; a nicer-looking output alone is not evidence that Skeinn caused the improvement.
|
|
33
|
+
|
|
34
|
+
## Release checks
|
|
35
|
+
|
|
36
|
+
Run `npm test` and `npm pack --dry-run` before requesting release. See the
|
|
37
|
+
[release checklist](docs/RELEASE_CHECKLIST.md) for the maintainer flow.
|
package/EVIL_EVAL.md
ADDED
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
# Evil Eval v2 — 三层高性价比评测体系
|
|
2
|
+
|
|
3
|
+
Evil Eval 只回答一个冷酷的问题:**Skeinn 到底有没有在真实项目里显著提升 Agent 的交付质量,还是只是多写了一堆看起来很严谨的文档?**
|
|
4
|
+
|
|
5
|
+
为了既保证科学对照、又能以 **单次 ~¥20 人民币(适配 DeepSeek 4.1 Flash 等高性价比快模型)** 的成本高频跑起来,Evil Eval 按成本和用途拆成三层:
|
|
6
|
+
|
|
7
|
+
| 层级 | 命令模式 | 单次参考预算 | 适用时机 | 判定机制 |
|
|
8
|
+
| :--- | :--- | :--- | :--- | :--- |
|
|
9
|
+
| **L1:微探针(Micro-Probe)** | `mode: "probe"` | **¥2–¥5** | 每次改 `protocol.js` / `store.js` 后 | 5 项硬断言 Pass/Fail(防偷懒、禁伪调研、设计对撞、CLI 零摩擦、冷启动首步) |
|
|
10
|
+
| **L2:三棒盲接力赛(Relay Eval,主力推荐)** | `mode: "relay"` | **¥15–¥20** | 每个小版本 / 核心改动验收 | **3 棒零记忆接力 + 中途需求反转 + 隐藏自动化断言(Hidden Oracle)+ 三选一盲评 + 真实遥测** |
|
|
11
|
+
| **L3:完整发布评测(Full Eval)** | `mode: "full"` | **¥50–¥60** | 大版本发布前 / 消融实验 | 3 次重复 + 全量盲评 + 消融对照 |
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## 核心对照组(绝不削弱基线)
|
|
16
|
+
|
|
17
|
+
每个场景同时跑两条臂(Arm):
|
|
18
|
+
- **Baseline**:同等模型、工具、工作区、用户回答与预算,**无 Skeinn**(允许其自由规划、写文档、用自身记忆)。
|
|
19
|
+
- **Skeinn**:完全相同的模型与条件,仅允许后台静默使用 `skeinn` CLI。
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## 主力推荐:~¥20 人民币的 L2 三棒盲接力赛(`mode: "relay"`)
|
|
24
|
+
|
|
25
|
+
单轮原型任务很难拉开裸 Agent 与框架的差距。Skeinn 真正的护城河在**跨多次失忆接棒、中途推翻决策与专业域避坑**。一轮完整 L2 Relay 恰好把预算花在刀刃上:
|
|
26
|
+
|
|
27
|
+
1. **第 1 棒(塑形 + 纵向切片 1)**:两条臂分别拿到同一份原始需求,完成初步设计与第一个可运行切片。
|
|
28
|
+
2. **第 2 棒(清空上下文 + 中途方向反转)**:强制开启**零聊天记忆的新 Agent**,只读磁盘恢复项目,并注入一条实质性的中途需求变更(`pivot`),要求不破坏第 1 棒已成立的不变量。
|
|
29
|
+
3. **第 3 棒(清空上下文 + 边界加固与收口)**:再次开启**零记忆新 Agent**(可选降级为更轻模型测试交接韧性),补齐边界条件、运行验证并诚实报告盲点。
|
|
30
|
+
|
|
31
|
+
### ¥20 预算怎么分配(以 Flash 级快模型为例)
|
|
32
|
+
- **Baseline 3 棒**:约 ¥4–¥6
|
|
33
|
+
- **Skeinn 3 棒(含 1–2 个瓶颈 Capability 与 1 次独立 Keeper)**:约 ¥8–¥10
|
|
34
|
+
- **Hidden Oracle 自动化验收(`hidden-oracle.mjs`)**:**¥0**(纯本地 Node 脚本,客观零偏见)
|
|
35
|
+
- **双顺序盲评裁判(X→Y 与 Y→X 各一次)**:约 ¥2–¥3
|
|
36
|
+
- **合计**:稳定控制在 **¥15–¥20 / 次**,既不因省钱缩水到没参考意义,也不会重到跑不动。
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## 为什么废除 1–5 分制,改用“隐藏断言 + 三选一盲评 + 真实遥测”?
|
|
41
|
+
|
|
42
|
+
1. **隐藏断言脚本(`hidden-oracle.mjs`)**:Agent 施工期间完全不可见,收尾后直接跑客观检查(文件/契约存在性、零外链扫描、重启恢复、回归破损率),彻底消灭“嘴上说完成了”。
|
|
43
|
+
2. **强制三选一盲评(Pairwise Forced-Choice)**:废除容易打出 4 vs 5 贴脸分的 1–5 分制。裁判对 6 个维度只输出 **`X_CLEAR_WIN` / `TIE` / `Y_CLEAR_WIN`**,并强制交换顺序(X→Y 与 Y→X)复评,凡是翻转的结论一律标 **`UNSTABLE`**。
|
|
44
|
+
3. **真实遥测落盘(`telemetry-template.json`)**:强制记录每条臂的真实 `input_tokens`、`output_tokens`、`cost_cny`、`wall_seconds`、`tool_calls`、`cli_retries` 与 `hidden_oracle_passed`,直接计算**每元人民币换来的净质量提升**。
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
## 快速生成一个评测脚手架
|
|
49
|
+
|
|
50
|
+
准备 `scenario.json`:
|
|
51
|
+
|
|
52
|
+
```json
|
|
53
|
+
{
|
|
54
|
+
"id": "RELAY-001",
|
|
55
|
+
"title": "本地离线复盘工具三棒接力",
|
|
56
|
+
"mode": "relay",
|
|
57
|
+
"budget_cny": 20,
|
|
58
|
+
"brief": "做一个单文件本地离线的会议后 3 分钟复盘工具,刷新保留草稿,支持一键清空。",
|
|
59
|
+
"pivot": "第 2 棒中途新增:用户要求支持本地加密 JSON 导出与导入,但仍必须 100% 离线零外链。",
|
|
60
|
+
"hidden_checks": [
|
|
61
|
+
"静态扫描零外部 HTTP/CDN/字体请求",
|
|
62
|
+
"刷新后草稿完整恢复,一键清空后存储归零",
|
|
63
|
+
"加密导出再导入后数据无损且错误密码被诚实拒绝"
|
|
64
|
+
],
|
|
65
|
+
"human_channel": "unavailable",
|
|
66
|
+
"success_criteria": ["三棒零记忆接力后全部隐藏断言通过且无回归破损"]
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
运行:
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
skeinn eval scaffold --json-file scenario.json
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Skeinn 会在 `.skeinn/eval/<scenario>/` 下自动生成:
|
|
77
|
+
- `manifest.json`(控制变量与预算上限)
|
|
78
|
+
- `batons/baseline-baton-{1,2,3}.md` 与 `batons/skeinn-baton-{1,2,3}.md`(可直接喂给各棒新会话的提示词)
|
|
79
|
+
- `hidden-oracle.mjs`(填入你的客观断言脚本)
|
|
80
|
+
- `telemetry-template.json`(成本与重试遥测模板)
|
|
81
|
+
- `judge-prompt.md`(双顺序三选一盲评裁判提示词)
|
|
82
|
+
- 若 `mode: "probe"`,额外生成 `probe-checklist.md`(5 项 L1 防偷懒硬检查清单)。
|
|
83
|
+
|
|
84
|
+
> 无人值守运行 Skeinn 臂时,请配合 `--state-dir <工作区外目录>` 与 `--human-channel unavailable`,确保 `.skeinn/` 状态不污染被评测工作区。
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 haaaiawd
|
|
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,197 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<picture>
|
|
4
|
+
<source media="(prefers-color-scheme: dark)" srcset="docs/brand/skeinn-wordmark-dark.svg">
|
|
5
|
+
<source media="(prefers-color-scheme: light)" srcset="docs/brand/skeinn-wordmark-light.svg">
|
|
6
|
+
<img alt="Skeinn" src="docs/brand/skeinn-wordmark-light.svg" height="64">
|
|
7
|
+
</picture>
|
|
8
|
+
|
|
9
|
+
<p><strong>Remember the whole. Build like a practitioner.</strong></p>
|
|
10
|
+
<p>Invisible continuity, firsthand practitioner judgment, and proof infrastructure for AI coding agents.</p>
|
|
11
|
+
|
|
12
|
+
<p>
|
|
13
|
+
<strong>English</strong> · <a href="README.zh-CN.md">简体中文</a> ·
|
|
14
|
+
<a href="design.md">System Design</a> ·
|
|
15
|
+
<a href="EVIL_EVAL.md">Evil Eval</a> ·
|
|
16
|
+
<a href="CHANGELOG.md">Changelog</a>
|
|
17
|
+
</p>
|
|
18
|
+
|
|
19
|
+
<p>
|
|
20
|
+
<img src="https://img.shields.io/badge/node-%E2%89%A518-17212B?style=flat-square" alt="Node.js 18+">
|
|
21
|
+
<img src="https://img.shields.io/badge/for-AI%20Coding%20Agents-3B63F6?style=flat-square" alt="For AI Coding Agents">
|
|
22
|
+
<img src="https://img.shields.io/badge/languages-Multilingual-17212B?style=flat-square" alt="Multilingual">
|
|
23
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-9AD8C2?style=flat-square&labelColor=17212B" alt="MIT License"></a>
|
|
24
|
+
</p>
|
|
25
|
+
|
|
26
|
+
</div>
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## Why Skeinn?
|
|
31
|
+
|
|
32
|
+
AI coding feels effortless on small scripts, yet multi-day, multi-module projects under unstructured Vibe Coding reliably hit four walls:
|
|
33
|
+
|
|
34
|
+
| Failure mode | Unstructured Vibe Coding | Agent backed by Skeinn |
|
|
35
|
+
| :--- | :--- | :--- |
|
|
36
|
+
| **Context amnesia** | Compaction or a new session wipes out architecture, boundaries, and earlier corrections | Project truth, decisions, progress, and proof live on disk; a fresh Agent resumes directly |
|
|
37
|
+
| **Generic average output** | Models default to safe statistical averages that look templated and amateur | Targets 1–3 bottleneck domains, **researches how real practitioners operate**, and reflects on project constraints |
|
|
38
|
+
| **First-draft lock-in** | Codes the first plausible idea immediately, hiding expensive rework | Core designs force **at least 2 genuinely viable alternatives** (including a simpler or unconventional angle) |
|
|
39
|
+
| **False-green completion** | Claims "done" while missing files, skipping edge cases, or breaking upstream work | A **fresh independent Keeper** gates launch on the active horizon — minors pass as advisories pinned to their Task/doc and surface at `task start` — while per-artifact digests drive delta re-checks and in-flight drift checkpoints; every Task closes with reproducible evidence |
|
|
40
|
+
|
|
41
|
+
> **Core rule: Skeinn is for the Agent, not the human.**
|
|
42
|
+
> Multilingual by default — talk naturally in English, Chinese, Japanese, or any language you prefer. The Agent operates the `skeinn` CLI silently in the background.
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## How a real project flows
|
|
47
|
+
|
|
48
|
+
```text
|
|
49
|
+
You (natural chat in any language) Agent (silent skeinn CLI on disk)
|
|
50
|
+
─────────────────────────────────────────────────────────────────────────
|
|
51
|
+
1. Share an early idea Inspect workspace → ask one dense
|
|
52
|
+
"Build an offline reflection tool..." batch of consequential questions
|
|
53
|
+
|
|
54
|
+
2. Settle key tradeoffs Anchor PROJECT.md → iterate core
|
|
55
|
+
Design docs & 1–3 bottleneck
|
|
56
|
+
Capabilities (practitioner research
|
|
57
|
+
→ reflection → Design delta)
|
|
58
|
+
|
|
59
|
+
3. Confirm the whole Freeze digest → fresh zero-memory
|
|
60
|
+
Keeper gates launch on the active
|
|
61
|
+
horizon; minors pin to scope
|
|
62
|
+
|
|
63
|
+
4. See working slices, steer anytime Execute one restartable Task at a
|
|
64
|
+
time with guardrails & exact proof;
|
|
65
|
+
drift checkpoints & stale-work flags
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## What real Skeinn artifacts look like
|
|
71
|
+
|
|
72
|
+
Example: building a **3-minute offline post-meeting reflection tool**.
|
|
73
|
+
|
|
74
|
+
### 1. Bottleneck capability (`.skeinn/capabilities/reflective-ux.md`)
|
|
75
|
+
|
|
76
|
+
```markdown
|
|
77
|
+
# Reflective UX Design
|
|
78
|
+
- Mode: external_researched
|
|
79
|
+
- Authority: human_confirmed
|
|
80
|
+
|
|
81
|
+
## How real practitioners operate
|
|
82
|
+
- Progressive disclosure with low-cognitive-load single-column flows — Source: https://linear.app/method
|
|
83
|
+
- Local-first tools surface storage boundaries and instant deletion upfront — Source: https://localfirstweb.dev/
|
|
84
|
+
|
|
85
|
+
## Reflection for this project
|
|
86
|
+
- What to refuse: streaks, mood scores, and timers create assessment anxiety right after a tense meeting.
|
|
87
|
+
- Non-obvious craft move: mirror the user's own phrasing and let them pick one small next step instead of AI lecturing.
|
|
88
|
+
|
|
89
|
+
## Operational rules and Design delta
|
|
90
|
+
- Anti-patterns: countdown timers, emotion ratings, silent network requests
|
|
91
|
+
- Design delta (Before -> After): Replaced 3-pane dashboard with a skippable 4-step single-column flow + upfront clear control.
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### 2. Decision-collision design (`.skeinn/design/first-use-flow.md`)
|
|
95
|
+
|
|
96
|
+
```markdown
|
|
97
|
+
## Alternatives considered
|
|
98
|
+
- Option A (chosen): Single self-contained HTML file + localStorage (zero install, instant open, provably offline).
|
|
99
|
+
- Option B (rejected): Vite + local SQLite server. More extensible, but breaks zero-friction 3-minute use.
|
|
100
|
+
|
|
101
|
+
## How this could look done yet fail
|
|
102
|
+
- Tests pass, yet a remote Google Font leaks network traffic or page reload silently drops an in-progress draft.
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### 3. Restartable Task with guardrails (`.skeinn/tasks.json`)
|
|
106
|
+
|
|
107
|
+
```json
|
|
108
|
+
{
|
|
109
|
+
"id": "TASK-001",
|
|
110
|
+
"title": "Build offline reflection flow and instant local wipe",
|
|
111
|
+
"implements": ".skeinn/design/first-use-flow.md#Alternatives considered",
|
|
112
|
+
"guardrails": [
|
|
113
|
+
"Zero external network requests, remote fonts, or analytics scripts",
|
|
114
|
+
"No emotion scoring, timers, or mandatory completion locks"
|
|
115
|
+
],
|
|
116
|
+
"acceptance": [
|
|
117
|
+
{
|
|
118
|
+
"criterion": "Static scan finds zero external URLs; reload restores draft; clear wipes storage",
|
|
119
|
+
"verify_by": "Run node tests/verify.mjs and verify reload/clear in browser",
|
|
120
|
+
"evidence": "verify.mjs: 0 external URLs; reload restored draft; clear wiped localStorage"
|
|
121
|
+
}
|
|
122
|
+
]
|
|
123
|
+
}
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## Quick start
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
npm install --global @haaaiawd/skeinn
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Open your coding Agent (Claude Code, Cursor, Windsurf, Codex, etc.) in your project directory and say:
|
|
135
|
+
|
|
136
|
+
> "This project uses Skeinn for continuity and design quality. Run `skeinn init` and `skeinn context --full` to load the protocol; talk to me naturally and maintain state silently in the background."
|
|
137
|
+
|
|
138
|
+
<details>
|
|
139
|
+
<summary><strong>Agent CLI quick reference (for Agents, not humans)</strong></summary>
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
skeinn init
|
|
143
|
+
skeinn context --full # first entry or after context reset
|
|
144
|
+
skeinn context # lean resume between Tasks
|
|
145
|
+
skeinn record --json-file understanding.json
|
|
146
|
+
skeinn design add core --title "Core system" --kind system
|
|
147
|
+
skeinn capability add ui-ux --title "UI/UX design" --mode external_researched
|
|
148
|
+
skeinn capability confirm ui-ux --scenario "<project scenario>" --source human
|
|
149
|
+
skeinn capability exempt --reason "<why standard engineering suffices>"
|
|
150
|
+
skeinn deliverable add cli-core --title "CLI core" --kind module
|
|
151
|
+
skeinn task plan --json-file work-map.json
|
|
152
|
+
skeinn project ready
|
|
153
|
+
skeinn keeper record --json-file keeper-result.json
|
|
154
|
+
skeinn keeper resolve FND-001 --evidence "<closure proof>" # close a pinned finding
|
|
155
|
+
skeinn keeper checkpoint prompt --milestone M1 # in-flight drift audit
|
|
156
|
+
skeinn keeper checkpoint record --json-file checkpoint-result.json
|
|
157
|
+
skeinn context --checkpoint # checkpoint-scoped slice
|
|
158
|
+
# kind: "spike" tasks may start during shaping for empirical unknowns
|
|
159
|
+
skeinn task next && skeinn task start TASK-001
|
|
160
|
+
skeinn task done TASK-001 --json-file evidence.json
|
|
161
|
+
skeinn check
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
</details>
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## Verify it actually helps
|
|
169
|
+
|
|
170
|
+
Run `npm test` (38 end-to-end contract tests), or use `skeinn eval scaffold` to run controlled **Evil Eval** comparisons (equal model, tools, workspace, user facts, forced resets, and blind order-swapped judging). See [EVIL_EVAL.md](EVIL_EVAL.md).
|
|
171
|
+
|
|
172
|
+
### A real measured run
|
|
173
|
+
|
|
174
|
+
We ran the full L2 relay on **DeepSeek-V4.1-Flash** — a cheap model where framework gains should be most visible. Same harness (opencode), same workspace rules, same brief: build the single-file offline 3-minute retro tool above, across **3 batons with hard memory resets**, with a mid-project pivot to encrypted export/import. Then a hidden oracle, and two independent blind judges scoring sealed X/Y packets in swapped order.
|
|
175
|
+
|
|
176
|
+
```text
|
|
177
|
+
Hidden oracle (8 objective checks) baseline 8/8 skeinn 8/8 ← parity
|
|
178
|
+
|
|
179
|
+
Total cost baseline ¥0.42 █████ skeinn ¥0.82 ██████████
|
|
180
|
+
Wall time baseline 35 m █████ skeinn 60 m █████████
|
|
181
|
+
Tokens (in+out+reason) baseline 330 k ████ skeinn 741 k █████████
|
|
182
|
+
Tests shipped baseline 43 ██████████ skeinn 44 ██████████
|
|
183
|
+
(pytest + Playwright) (zero-dep `node --test`,
|
|
184
|
+
real headless Chrome)
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
| Dimension (forced choice) | Judge pass 1 | Judge pass 2 |
|
|
188
|
+
| :--- | :--- | :--- |
|
|
189
|
+
| Intent fidelity & pivot survival | **Skeinn** | Tie |
|
|
190
|
+
| Specialist capability & craft | **Skeinn** | **Skeinn** |
|
|
191
|
+
| Cold-handoff continuity | Tie | Tie |
|
|
192
|
+
| Oracle & proof honesty | Tie | Tie |
|
|
193
|
+
| User burden & ceremony | **Skeinn** | **Skeinn** |
|
|
194
|
+
| Net value per RMB | **Baseline** | **Baseline** |
|
|
195
|
+
| **Overall** | **Skeinn** | **Skeinn** |
|
|
196
|
+
|
|
197
|
+
*Caveats we keep honest: single run, single scenario, n=2 judges. The evidence judges cited, baseline's cost-efficiency win, and one packet-metadata leak we found and fixed-forward are in the full log: [docs/eval/RELAY-001.md](docs/eval/RELAY-001.md).*
|