@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/README.zh-CN.md
ADDED
|
@@ -0,0 +1,262 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
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>记住全貌,像高手一样把项目做完。</strong></p>
|
|
10
|
+
<p>为 AI 编码 Agent 打造的隐形项目理解、一线专业判准与断电续接底座。</p>
|
|
11
|
+
|
|
12
|
+
<p>
|
|
13
|
+
<a href="README.md">English</a> · <strong>简体中文</strong> ·
|
|
14
|
+
<a href="design.md">系统设计</a> ·
|
|
15
|
+
<a href="EVIL_EVAL.md">Evil Eval</a> ·
|
|
16
|
+
<a href="CHANGELOG.md">更新日志</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
|
+
## 为什么需要 Skeinn?
|
|
31
|
+
|
|
32
|
+
用 AI 写几百行脚本很顺,但一旦进入**三天以上、多模块的中大型项目**,无规则 Vibe Coding 几乎都会撞上四堵墙:
|
|
33
|
+
|
|
34
|
+
| 痛点 | 无规则 Vibe Coding | 接入 Skeinn 后的 Agent |
|
|
35
|
+
| :--- | :--- | :--- |
|
|
36
|
+
| **聊久就失忆** | 上下文压缩或新开会话后,架构决策、边界和偏好全丢,越改越散 | 项目全貌、设计、任务进度与证据全部落盘,换新 Agent 直接续接 |
|
|
37
|
+
| **方案平庸、像外行** | 默认收敛到“互联网统计学平均解”,界面与架构一看就是模板拼凑 | 锁定 1–3 个瓶颈专业域,**调研真实一线从业者怎么干**并反思转化为项目规则 |
|
|
38
|
+
| **一稿过、后期返工** | 想到第一个可行方案就开写,隐患全部埋在实现阶段 | 核心设计强制**至少 2 个真实可行方案对撞**(含更简或非常规视角),写清取舍 |
|
|
39
|
+
| **假绿灯完成** | Agent 口头宣布“已实现”,实测缺文件、漏边界或改坏上游 | **全新无记忆 Keeper** 对拓扑前沿独立验盘起跑,minor 钉到具体 Task/文档并在 task start 自动浮出;施工中由逐工件摘要比对驱动轻量漂移巡检;每个 Task 凭可复现证据逐条关闭 |
|
|
40
|
+
|
|
41
|
+
> **核心原则:Skeinn 是给 Agent 用的,不是给人学的新框架。**
|
|
42
|
+
> 它天然支持多语言协作——你用中文、英文、日文或任何语言自然聊天即可;Agent 在后台静默调用 `skeinn` CLI 维护 `.skeinn/` 状态,你永远不需要手动敲这些命令。
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## 30 秒看懂一次真实协作
|
|
47
|
+
|
|
48
|
+
```text
|
|
49
|
+
你(用任意语言自然对话) Agent(后台静默运行 skeinn)
|
|
50
|
+
─────────────────────────────────────────────────────────────────────────
|
|
51
|
+
1. 抛出想法 检查工作区 → 只问真正改变方案的
|
|
52
|
+
"帮我做一个本地离线复盘工具..." 关键问题 → 记录事实、假设与边界
|
|
53
|
+
|
|
54
|
+
2. 回答关键取舍 写清 PROJECT.md → 迭代核心 Design
|
|
55
|
+
与 1–3 个瓶颈 Capability(查一线
|
|
56
|
+
实操 → 项目反思 → 写回 Design Delta)
|
|
57
|
+
|
|
58
|
+
3. 确认整体方向 冻结摘要 → 全新 Keeper 验盘前沿:
|
|
59
|
+
能否开工?伪调研/稻草人/红线?
|
|
60
|
+
minor 钉到具体任务,不再空转
|
|
61
|
+
|
|
62
|
+
4. 陆续看到可运行成果,随时提新想法 一次只做 1 个可恢复 Task(自带
|
|
63
|
+
guardrails 红线),逐条填实证闭环;
|
|
64
|
+
巡检对账漂移,改方向标出受影响任务
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## 真实产物长什么样?(具体演示)
|
|
70
|
+
|
|
71
|
+
以**“做一个本地离线的会议后 3 分钟复盘工具”**为例,看看 Skeinn 在后台到底帮 Agent 沉淀了什么高价值内容(而不是一堆废话文档):
|
|
72
|
+
|
|
73
|
+
### 1. 一份瓶颈领域判准(`.skeinn/capabilities/reflective-ux.md`)
|
|
74
|
+
|
|
75
|
+
```markdown
|
|
76
|
+
# Reflective UX Design
|
|
77
|
+
- Mode: external_researched
|
|
78
|
+
- Authority: human_confirmed
|
|
79
|
+
|
|
80
|
+
## How real practitioners operate
|
|
81
|
+
- 渐进披露与单屏低认知负荷 — Source: https://linear.app/method
|
|
82
|
+
- 敏感个人笔记工具必须将“本地存储边界与一键清空”前置可见,而非藏进隐私条款 — Source: https://localfirstweb.dev/
|
|
83
|
+
|
|
84
|
+
## Reflection for this project
|
|
85
|
+
- 哪些不能照搬:大厂日记 App 的“连续打卡/情绪打分”会给刚开完高压会议的人制造考核焦虑,必须砍掉。
|
|
86
|
+
- 高手的非显性手法:用“原话回显 + 自主选下一步”替代 AI 总结说教,让用户感到被托住而不是被评估。
|
|
87
|
+
|
|
88
|
+
## Operational rules and Design delta
|
|
89
|
+
- Anti-patterns: 禁止倒计时、禁止情绪打分、禁止任何静默外链请求
|
|
90
|
+
- Design delta (Before -> After): 将首屏从“3 栏仪表盘 + 情绪雷达图”改为“4 步可跳过单栏卡片流”,并在首屏直接暴露一键清除按钮。
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### 2. 一段方案对撞设计(`.skeinn/design/first-use-flow.md`)
|
|
94
|
+
|
|
95
|
+
```markdown
|
|
96
|
+
## Alternatives considered
|
|
97
|
+
- 方案 A(采纳):单 HTML 文件 + localStorage 渐进式 4 步卡片流(零安装、双击即用、离线可验)。
|
|
98
|
+
- 方案 B(否决):Vite + SQLite 本地服务版。虽然扩展性更强,但违背“会后 3 分钟零摩擦打开”的核心体验。
|
|
99
|
+
|
|
100
|
+
## How this could look done yet fail
|
|
101
|
+
- 页面跑通、测试全绿,但引入了远程 Google Fonts 导致弱网下泄漏请求;或刷新页面后草稿静默丢失。
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
### 3. 一条带防呆红线的可恢复 Task(`.skeinn/tasks.json`)
|
|
105
|
+
|
|
106
|
+
```json
|
|
107
|
+
{
|
|
108
|
+
"id": "TASK-001",
|
|
109
|
+
"title": "实现单文件离线复盘主流程与本地清空",
|
|
110
|
+
"implements": ".skeinn/design/first-use-flow.md#Alternatives considered",
|
|
111
|
+
"guardrails": [
|
|
112
|
+
"禁止任何外部网络请求、远程字体或分析脚本",
|
|
113
|
+
"禁止添加情绪打分、倒计时或强制填写校验"
|
|
114
|
+
],
|
|
115
|
+
"acceptance": [
|
|
116
|
+
{
|
|
117
|
+
"criterion": "源码静态扫描零外链请求,刷新后草稿保留且一键清空生效",
|
|
118
|
+
"verify_by": "运行 node tests/verify.mjs 并在浏览器实测刷新与清空",
|
|
119
|
+
"evidence": "verify.mjs: 0 external URLs; reload restored draft; clear wiped localStorage"
|
|
120
|
+
}
|
|
121
|
+
]
|
|
122
|
+
}
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
---
|
|
126
|
+
|
|
127
|
+
## 四个核心设计:低摩擦,且防偷懒
|
|
128
|
+
|
|
129
|
+
1. **单文件 Capability(真调研 + 真反思 + Design Delta)**:聚焦 1–3 个决定上限的瓶颈域,1 条命令创建 `.skeinn/capabilities/<field>.md`。禁止静默跳过(纯常规工程必须显式 `skeinn capability exempt` 并接受 Keeper 审计);`external_researched` 直接拦截 `agent-authored` 自造来源;无网时诚实标 `offline_reflection`。
|
|
130
|
+
2. **方案对撞型 Design**:核心设计(`product` / `experience` / `system` / `contract`)强制对比至少 2 个真实可行方案(含更简或非常规视角),把 Capability 判准编译进机制,并提前写清假阳性失败面。
|
|
131
|
+
3. **前沿起跑 + 行进间巡检 Keeper**:开工前由全新无记忆 Agent 只对当前拓扑前沿(可执行任务及其 1–2 跳后继、关联设计文档)做独立验盘,四项反敷衍核查不变;仅余 minor 项时按 `passed_with_advisories` 放行并钉到具体 Task/文档,`task start` 时自动浮出,第 2 轮起只对变更文件做 Delta 复核;施工中由逐工件 `reviewed_digests` 差集驱动轻量 checkpoint 漂移巡检,出生证明一次签发不再重跑。
|
|
132
|
+
4. **可恢复 Task + 防呆红线**:广度 Work Map 留盘,每次只注入当前唯一活跃 Task、精确 `reads` 与 1–3 条 `guardrails`;完成校验产出存在与逐条实证,上游重开自动标出需要复核的下游任务。
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
136
|
+
## 快速开始
|
|
137
|
+
|
|
138
|
+
### 1. 安装 CLI(Node.js ≥ 18)
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
npm install --global @haaaiawd/skeinn
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
或从源码仓库本地安装:
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
npm install --global .
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
### 2. 把这句话交给你的编码 Agent
|
|
151
|
+
|
|
152
|
+
在项目目录中打开 Claude Code / Cursor / Windsurf / Codex 等具备终端能力的 Agent,直接说:
|
|
153
|
+
|
|
154
|
+
> “这个项目使用 Skeinn 维护项目理解与连续性。请先运行 `skeinn init` 和 `skeinn context --full` 读取协议;之后你只管和我自然沟通,在后台维护项目状态。”
|
|
155
|
+
|
|
156
|
+
---
|
|
157
|
+
|
|
158
|
+
## 磁盘结构
|
|
159
|
+
|
|
160
|
+
```text
|
|
161
|
+
.skeinn/
|
|
162
|
+
├── PROJECT.md 项目全貌入口与导航图
|
|
163
|
+
├── STRUCTURE.md 代码、测试、文档与资源目录约定
|
|
164
|
+
├── DECISIONS.md 重要决策变更与受影响任务记录
|
|
165
|
+
├── capabilities/ 1–3 份单文件瓶颈领域判准(一线实操 + 反思 + Design Delta)
|
|
166
|
+
├── design/ 按子系统拆分的设计文档图谱(含方案对撞与假阳性失败面)
|
|
167
|
+
├── state.json 已确认事实、假设、未决问题、豁免与 Keeper 状态
|
|
168
|
+
├── deliverables.json 可观察交付面(区分已规划与已交付)
|
|
169
|
+
└── tasks.json 磁盘上的广度 Work Map 与当前活跃 Task
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
<details>
|
|
173
|
+
<summary><strong>Agent CLI 速查(仅 Agent 在后台调用,人类无需记忆)</strong></summary>
|
|
174
|
+
|
|
175
|
+
```bash
|
|
176
|
+
# 初始化与上下文恢复(首次进入或重置后用 --full,任务间隙用精简 context)
|
|
177
|
+
skeinn init
|
|
178
|
+
skeinn context --full
|
|
179
|
+
skeinn context
|
|
180
|
+
|
|
181
|
+
# 记录理解、迭代设计与瓶颈能力
|
|
182
|
+
skeinn record --json-file understanding.json
|
|
183
|
+
skeinn design add core --title "Core system" --kind system
|
|
184
|
+
skeinn capability add ui-ux --title "UI/UX design" --mode external_researched
|
|
185
|
+
skeinn capability confirm ui-ux --scenario "<项目情境>" --source human
|
|
186
|
+
# 纯常规工程无需专项能力时显式豁免(由 Keeper 审计):
|
|
187
|
+
skeinn capability exempt --reason "<为何常规工程能力已足够>"
|
|
188
|
+
|
|
189
|
+
# 规划交付面与任务,冻结摘要并由独立 Keeper 验盘
|
|
190
|
+
skeinn deliverable add cli-core --title "CLI core" --kind module
|
|
191
|
+
skeinn task plan --json-file work-map.json
|
|
192
|
+
skeinn project ready
|
|
193
|
+
# 新开无继承上下文的 Agent 运行 skeinn keeper prompt,并提交含 review.mode: "independent" 的结果
|
|
194
|
+
skeinn keeper record --json-file keeper-result.json
|
|
195
|
+
# 钉在 Task/文档上的 finding 凭证据核销;施工中巡检漂移与迟到前沿工件:
|
|
196
|
+
skeinn keeper resolve FND-001 --evidence "<核销证明>"
|
|
197
|
+
skeinn keeper checkpoint prompt --milestone M1
|
|
198
|
+
skeinn keeper checkpoint record --json-file checkpoint-result.json
|
|
199
|
+
skeinn context --checkpoint
|
|
200
|
+
|
|
201
|
+
# 单任务实证施工与变更演化(kind: "spike" 任务可在起跑前做经验性试跑)
|
|
202
|
+
skeinn task next
|
|
203
|
+
skeinn task start TASK-001
|
|
204
|
+
skeinn task done TASK-001 --json-file evidence.json # 详见 skeinn task done --help
|
|
205
|
+
skeinn decision --json-file decision.json
|
|
206
|
+
skeinn clarify start --reason "<方向变化原因>"
|
|
207
|
+
skeinn check
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
> 无人值守或 Benchmark 运行时,可附加 `--human-channel unavailable` 与 `--state-dir <外部目录>`,在不污染评分工作区的前提下保持完整状态。
|
|
211
|
+
|
|
212
|
+
</details>
|
|
213
|
+
|
|
214
|
+
---
|
|
215
|
+
|
|
216
|
+
## 证明它真的有用(Evil Eval)
|
|
217
|
+
|
|
218
|
+
内置 **Evil Eval** 脚手架:在完全相同的模型、工具、工作区、用户事实与预算下,对“无框架基线”与“接入 Skeinn”执行**强制上下文重置 + 匿名盲评 + 顺序交换**,把仪式成本、用户负担与最终质量一起计分。详见 [EVIL_EVAL.md](EVIL_EVAL.md)。
|
|
219
|
+
|
|
220
|
+
```bash
|
|
221
|
+
npm test
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
### 一次真实实测
|
|
225
|
+
|
|
226
|
+
我们在 **DeepSeek-V4.1-Flash** 上跑完了完整的 L2 接力实验——便宜模型上框架增益最容易拉开差距。同一 harness(opencode)、同一工作区规则、同一题目(上面的单文件离线 3 分钟复盘工具),**3 棒之间硬性清零记忆**,中途塞入加密导入导出需求反转;跑完后由隐藏 oracle 验收,再由两名互不知情的裁判对密封 X/Y 工件包做顺序交换盲评。
|
|
227
|
+
|
|
228
|
+
```text
|
|
229
|
+
隐藏 oracle(8 项客观断言) baseline 8/8 skeinn 8/8 ← 持平
|
|
230
|
+
|
|
231
|
+
总成本 baseline ¥0.42 █████ skeinn ¥0.82 ██████████
|
|
232
|
+
耗时 baseline 35 m █████ skeinn 60 m █████████
|
|
233
|
+
Token(输入+输出+推理) baseline 330 k ████ skeinn 741 k █████████
|
|
234
|
+
交付测试数 baseline 43 ██████████ skeinn 44 ██████████
|
|
235
|
+
(pytest + Playwright) (零依赖 `node --test`,
|
|
236
|
+
真实无头 Chrome)
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
| 维度(强制二选一) | 裁判 1(X→Y) | 裁判 2(Y→X) |
|
|
240
|
+
| :--- | :--- | :--- |
|
|
241
|
+
| 意图保真与反转存活 | **Skeinn** | 平 |
|
|
242
|
+
| 专业能力深度 | **Skeinn** | **Skeinn** |
|
|
243
|
+
| 冷交接连续性 | 平 | 平 |
|
|
244
|
+
| Oracle 与实证诚实度 | 平 | 平 |
|
|
245
|
+
| 用户负担与仪式感 | **Skeinn** | **Skeinn** |
|
|
246
|
+
| 性价比 | **Baseline** | **Baseline** |
|
|
247
|
+
| **总判** | **Skeinn** | **Skeinn** |
|
|
248
|
+
|
|
249
|
+
*诚实的边界:单次实验、单一场景、n=2 裁判。裁判引用的具体证据、baseline 的性价比胜利、以及我们发现的一处工件包元数据泄漏,见完整遥测与判决日志:[docs/eval/RELAY-001.md](docs/eval/RELAY-001.md)。*
|
|
250
|
+
|
|
251
|
+
---
|
|
252
|
+
|
|
253
|
+
## 文档导航
|
|
254
|
+
|
|
255
|
+
| 文档 | 内容 |
|
|
256
|
+
| :--- | :--- |
|
|
257
|
+
| [系统设计](design.md) | 架构、存储模型、不变量与命令契约 |
|
|
258
|
+
| [UX 与闭环规范](docs/UX_FLOW.md) | 人、Agent、Keeper 与 Task 的完整转换 |
|
|
259
|
+
| [提示词目录](docs/PROMPT_CATALOG.md) | 注入给 Agent 的全部认知层与模板 |
|
|
260
|
+
| [Evil Eval 协议](EVIL_EVAL.md) | 有无框架的受控对照实验规范 |
|
|
261
|
+
| [RELAY-001 实测日志](docs/eval/RELAY-001.md) | DS-Flash 三棒接力的完整遥测与盲评判决 |
|
|
262
|
+
| [更新日志](CHANGELOG.md) | v2.5.0 及历次演进记录 |
|
package/SECURITY.md
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Security policy
|
|
2
|
+
|
|
3
|
+
Please do not publish exploitable details in a public issue.
|
|
4
|
+
|
|
5
|
+
Report a vulnerability through [GitHub private vulnerability reporting](https://github.com/Haaaiawd/skeinn/security/advisories/new).
|
|
6
|
+
Include the affected version, reproduction steps, impact, and any suggested mitigation. If private reporting
|
|
7
|
+
is unavailable, open a minimal issue asking for a private contact channel without including the vulnerability.
|
|
8
|
+
|
|
9
|
+
Skeinn reads and writes project-local state and may be used by Agents with broad command-line permissions.
|
|
10
|
+
Security reports involving path traversal, unintended workspace mutation, command construction, stale Keeper
|
|
11
|
+
authorization, or untrusted project content are especially relevant.
|