maestro-flow 0.5.33 → 0.5.34
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/.agents/agents/role-design-author.md +5 -3
- package/.agents/skills/maestro/SKILL.md +8 -1
- package/.agents/skills/maestro-help/SKILL.md +39 -10
- package/.agents/skills/maestro-help/index/catalog.json +118 -53
- package/.agents/skills/maestro-help/phases/01-parse-intent.md +9 -6
- package/.agents/skills/maestro-help/phases/02-search-present.md +55 -15
- package/.agents/skills/maestro-help/phases/03-workflow-guide.md +35 -2
- package/.agents/skills/maestro-ralph/SKILL.md +9 -2
- package/.agents/skills/maestro-ralph-beta/SKILL.md +7 -2
- package/.agents/skills/maestro-ralph-execute/SKILL.md +1 -0
- package/.agents/skills/manage-harvest/SKILL.md +3 -0
- package/.agents/skills/manage-knowledge-audit/SKILL.md +29 -0
- package/.agents/skills/odyssey-debug/SKILL.md +7 -1
- package/.agents/skills/odyssey-improve/SKILL.md +7 -1
- package/.agents/skills/odyssey-planex/SKILL.md +11 -1
- package/.agents/skills/odyssey-review-test-fix/SKILL.md +7 -1
- package/.agents/skills/odyssey-ui/SKILL.md +7 -1
- package/.agents/skills/quality-review/SKILL.md +3 -0
- package/.agy/agents/role-design-author.md +5 -3
- package/.agy/skills/maestro/SKILL.md +8 -1
- package/.agy/skills/maestro-help/SKILL.md +39 -10
- package/.agy/skills/maestro-help/index/catalog.json +118 -53
- package/.agy/skills/maestro-help/phases/01-parse-intent.md +9 -6
- package/.agy/skills/maestro-help/phases/02-search-present.md +55 -15
- package/.agy/skills/maestro-help/phases/03-workflow-guide.md +35 -2
- package/.agy/skills/maestro-ralph/SKILL.md +9 -2
- package/.agy/skills/maestro-ralph-beta/SKILL.md +7 -2
- package/.agy/skills/maestro-ralph-execute/SKILL.md +1 -0
- package/.agy/skills/manage-harvest/SKILL.md +3 -0
- package/.agy/skills/manage-knowledge-audit/SKILL.md +29 -0
- package/.agy/skills/odyssey-debug/SKILL.md +7 -1
- package/.agy/skills/odyssey-improve/SKILL.md +7 -1
- package/.agy/skills/odyssey-planex/SKILL.md +11 -1
- package/.agy/skills/odyssey-review-test-fix/SKILL.md +7 -1
- package/.agy/skills/odyssey-ui/SKILL.md +7 -1
- package/.agy/skills/quality-review/SKILL.md +3 -0
- package/.claude/agents/role-design-author.md +5 -3
- package/.claude/commands/maestro-ralph-beta.md +7 -2
- package/.claude/commands/maestro-ralph-execute.md +1 -0
- package/.claude/commands/maestro-ralph.md +9 -2
- package/.claude/commands/maestro.md +8 -1
- package/.claude/commands/manage-harvest.md +3 -0
- package/.claude/commands/manage-knowledge-audit.md +29 -0
- package/.claude/commands/odyssey-debug.md +7 -1
- package/.claude/commands/odyssey-improve.md +7 -1
- package/.claude/commands/odyssey-planex.md +11 -1
- package/.claude/commands/odyssey-review-test-fix.md +7 -1
- package/.claude/commands/odyssey-ui.md +7 -1
- package/.claude/commands/quality-review.md +3 -0
- package/.claude/skills/maestro-help/SKILL.md +39 -10
- package/.claude/skills/maestro-help/index/catalog.json +118 -53
- package/.claude/skills/maestro-help/phases/01-parse-intent.md +9 -6
- package/.claude/skills/maestro-help/phases/02-search-present.md +55 -15
- package/.claude/skills/maestro-help/phases/03-workflow-guide.md +35 -2
- package/.codex/skills/manage-harvest/SKILL.md +2 -1
- package/.codex/skills/quality-review/SKILL.md +4 -2
- package/README.md +196 -87
- package/README.zh-CN.md +198 -79
- package/dashboard/dist-server/dashboard/src/server/wiki/graph-analysis.js +9 -4
- package/dashboard/dist-server/dashboard/src/server/wiki/graph-analysis.js.map +1 -1
- package/dashboard/dist-server/dashboard/src/server/wiki/search.d.ts +8 -5
- package/dashboard/dist-server/dashboard/src/server/wiki/search.js +22 -42
- package/dashboard/dist-server/dashboard/src/server/wiki/search.js.map +1 -1
- package/dashboard/dist-server/dashboard/src/server/wiki/wiki-indexer.d.ts +1 -4
- package/dashboard/dist-server/dashboard/src/server/wiki/wiki-indexer.js +28 -42
- package/dashboard/dist-server/dashboard/src/server/wiki/wiki-indexer.js.map +1 -1
- package/dashboard/dist-server/dashboard/src/server/wiki/wiki-indexer.test.js +22 -22
- package/dashboard/dist-server/dashboard/src/server/wiki/wiki-indexer.test.js.map +1 -1
- package/dashboard/dist-server/dashboard/src/server/wiki/writer-stress.test.js +12 -12
- package/dashboard/dist-server/dashboard/src/server/wiki/writer-stress.test.js.map +1 -1
- package/dashboard/dist-server/dashboard/src/server/wiki/writer.js +10 -3
- package/dashboard/dist-server/dashboard/src/server/wiki/writer.js.map +1 -1
- package/dashboard/dist-server/src/graph/kg/db/types.d.ts +2 -1
- package/dashboard/dist-server/src/graph/kg/db/types.js.map +1 -1
- package/dashboard/dist-server/src/graph/kg/extraction/knowledge-extractor-registry.d.ts +22 -0
- package/dashboard/dist-server/src/graph/kg/extraction/knowledge-extractor-registry.js +64 -0
- package/dashboard/dist-server/src/graph/kg/extraction/knowledge-extractor-registry.js.map +1 -0
- package/dashboard/dist-server/src/graph/kg/extraction/orchestrator.js +12 -98
- package/dashboard/dist-server/src/graph/kg/extraction/orchestrator.js.map +1 -1
- package/dashboard/dist-server/src/hooks/keyword-spec-injector.js +5 -2
- package/dashboard/dist-server/src/hooks/keyword-spec-injector.js.map +1 -1
- package/dashboard/dist-server/src/hooks/wiki-role-loader.js +2 -1
- package/dashboard/dist-server/src/hooks/wiki-role-loader.js.map +1 -1
- package/dashboard/dist-server/src/tools/domain-loader.js +22 -16
- package/dashboard/dist-server/src/tools/domain-loader.js.map +1 -1
- package/dashboard/dist-server/src/tools/spec-entry-parser.d.ts +6 -1
- package/dashboard/dist-server/src/tools/spec-entry-parser.js +44 -13
- package/dashboard/dist-server/src/tools/spec-entry-parser.js.map +1 -1
- package/dashboard/dist-server/src/tools/spec-keyword-index.d.ts +2 -0
- package/dashboard/dist-server/src/tools/spec-keyword-index.js +4 -9
- package/dashboard/dist-server/src/tools/spec-keyword-index.js.map +1 -1
- package/dashboard/dist-server/src/tools/spec-loader.js +3 -11
- package/dashboard/dist-server/src/tools/spec-loader.js.map +1 -1
- package/dashboard/dist-server/src/types/index.d.ts +14 -0
- package/dashboard/dist-server/src/utils/frontmatter.d.ts +15 -0
- package/dashboard/dist-server/src/utils/frontmatter.js +76 -0
- package/dashboard/dist-server/src/utils/frontmatter.js.map +1 -0
- package/dist/src/commands/domain.d.ts.map +1 -1
- package/dist/src/commands/domain.js +8 -2
- package/dist/src/commands/domain.js.map +1 -1
- package/dist/src/commands/install.d.ts.map +1 -1
- package/dist/src/commands/install.js +6 -2
- package/dist/src/commands/install.js.map +1 -1
- package/dist/src/commands/knowhow.d.ts.map +1 -1
- package/dist/src/commands/knowhow.js +3 -26
- package/dist/src/commands/knowhow.js.map +1 -1
- package/dist/src/commands/search.d.ts +1 -1
- package/dist/src/commands/search.d.ts.map +1 -1
- package/dist/src/commands/search.js +43 -41
- package/dist/src/commands/search.js.map +1 -1
- package/dist/src/commands/spec.d.ts.map +1 -1
- package/dist/src/commands/spec.js +106 -6
- package/dist/src/commands/spec.js.map +1 -1
- package/dist/src/commands/uninstall.d.ts.map +1 -1
- package/dist/src/commands/uninstall.js +12 -3
- package/dist/src/commands/uninstall.js.map +1 -1
- package/dist/src/config/cli-tools-config.d.ts.map +1 -1
- package/dist/src/config/cli-tools-config.js +2 -0
- package/dist/src/config/cli-tools-config.js.map +1 -1
- package/dist/src/core/extension-loader.d.ts.map +1 -1
- package/dist/src/core/extension-loader.js +4 -0
- package/dist/src/core/extension-loader.js.map +1 -1
- package/dist/src/core/install-executor.d.ts.map +1 -1
- package/dist/src/core/install-executor.js +2 -0
- package/dist/src/core/install-executor.js.map +1 -1
- package/dist/src/graph/analyzers/fs-analyzer.js +2 -2
- package/dist/src/graph/analyzers/fs-analyzer.js.map +1 -1
- package/dist/src/graph/kg/db/node-kind-registry.d.ts +18 -0
- package/dist/src/graph/kg/db/node-kind-registry.d.ts.map +1 -0
- package/dist/src/graph/kg/db/node-kind-registry.js +42 -0
- package/dist/src/graph/kg/db/node-kind-registry.js.map +1 -0
- package/dist/src/graph/kg/db/types.d.ts +2 -1
- package/dist/src/graph/kg/db/types.d.ts.map +1 -1
- package/dist/src/graph/kg/db/types.js.map +1 -1
- package/dist/src/graph/kg/extraction/knowledge-extractor-registry.d.ts +23 -0
- package/dist/src/graph/kg/extraction/knowledge-extractor-registry.d.ts.map +1 -0
- package/dist/src/graph/kg/extraction/knowledge-extractor-registry.js +64 -0
- package/dist/src/graph/kg/extraction/knowledge-extractor-registry.js.map +1 -0
- package/dist/src/graph/kg/extraction/orchestrator.d.ts.map +1 -1
- package/dist/src/graph/kg/extraction/orchestrator.js +12 -98
- package/dist/src/graph/kg/extraction/orchestrator.js.map +1 -1
- package/dist/src/hooks/keyword-spec-injector.d.ts.map +1 -1
- package/dist/src/hooks/keyword-spec-injector.js +5 -2
- package/dist/src/hooks/keyword-spec-injector.js.map +1 -1
- package/dist/src/hooks/wiki-role-loader.d.ts.map +1 -1
- package/dist/src/hooks/wiki-role-loader.js +2 -1
- package/dist/src/hooks/wiki-role-loader.js.map +1 -1
- package/dist/src/index.d.ts +6 -0
- package/dist/src/index.d.ts.map +1 -1
- package/dist/src/index.js +4 -0
- package/dist/src/index.js.map +1 -1
- package/dist/src/tools/domain-loader.d.ts.map +1 -1
- package/dist/src/tools/domain-loader.js +22 -16
- package/dist/src/tools/domain-loader.js.map +1 -1
- package/dist/src/tools/spec-conflict-marker.d.ts +55 -0
- package/dist/src/tools/spec-conflict-marker.d.ts.map +1 -0
- package/dist/src/tools/spec-conflict-marker.js +228 -0
- package/dist/src/tools/spec-conflict-marker.js.map +1 -0
- package/dist/src/tools/spec-entry-parser.d.ts +6 -1
- package/dist/src/tools/spec-entry-parser.d.ts.map +1 -1
- package/dist/src/tools/spec-entry-parser.js +44 -13
- package/dist/src/tools/spec-entry-parser.js.map +1 -1
- package/dist/src/tools/spec-keyword-index.d.ts +2 -0
- package/dist/src/tools/spec-keyword-index.d.ts.map +1 -1
- package/dist/src/tools/spec-keyword-index.js +4 -9
- package/dist/src/tools/spec-keyword-index.js.map +1 -1
- package/dist/src/tools/spec-loader.d.ts.map +1 -1
- package/dist/src/tools/spec-loader.js +3 -11
- package/dist/src/tools/spec-loader.js.map +1 -1
- package/dist/src/tools/spec-writer.d.ts.map +1 -1
- package/dist/src/tools/spec-writer.js +2 -6
- package/dist/src/tools/spec-writer.js.map +1 -1
- package/dist/src/tools/store-knowhow.d.ts.map +1 -1
- package/dist/src/tools/store-knowhow.js +6 -52
- package/dist/src/tools/store-knowhow.js.map +1 -1
- package/dist/src/tui/uninstall-ui/UninstallFlow.d.ts.map +1 -1
- package/dist/src/tui/uninstall-ui/UninstallFlow.js +3 -1
- package/dist/src/tui/uninstall-ui/UninstallFlow.js.map +1 -1
- package/dist/src/types/index.d.ts +14 -0
- package/dist/src/types/index.d.ts.map +1 -1
- package/dist/src/utils/frontmatter.d.ts +16 -0
- package/dist/src/utils/frontmatter.d.ts.map +1 -0
- package/dist/src/utils/frontmatter.js +76 -0
- package/dist/src/utils/frontmatter.js.map +1 -0
- package/dist/src/utils/migration-registry.d.ts.map +1 -1
- package/dist/src/utils/migration-registry.js +14 -1
- package/dist/src/utils/migration-registry.js.map +1 -1
- package/package.json +2 -2
- package/workflows/claude-instructions.md +48 -45
- package/workflows/codex-instructions.md +25 -19
package/README.zh-CN.md
CHANGED
|
@@ -2,22 +2,58 @@
|
|
|
2
2
|
|
|
3
3
|
# Maestro-Flow
|
|
4
4
|
|
|
5
|
-
###
|
|
5
|
+
### 多智能体时代的意图驱动工作流编排
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
**描述你想要什么,Maestro 负责搞定。**
|
|
8
8
|
|
|
9
|
+
<br/>
|
|
10
|
+
|
|
11
|
+
[](https://www.npmjs.com/package/maestro-flow)
|
|
9
12
|
[](https://www.typescriptlang.org/)
|
|
10
13
|
[](https://nodejs.org/)
|
|
11
14
|
[](https://modelcontextprotocol.io/)
|
|
12
15
|
[](LICENSE)
|
|
13
16
|
|
|
14
|
-
[English](README.md)
|
|
17
|
+
[English](README.md) | [简体中文](README.zh-CN.md)
|
|
15
18
|
|
|
16
19
|
</div>
|
|
17
20
|
|
|
18
|
-
|
|
21
|
+
<br/>
|
|
22
|
+
|
|
23
|
+
> 大多数 AI 编程工具只能让一个 agent 做一件事。
|
|
24
|
+
> Maestro-Flow 编排**多个 agent 横跨整个开发生命周期** — 从头脑风暴到部署上线 — 通过自适应决策引擎、自增强知识图谱和实时可视化仪表盘。
|
|
25
|
+
|
|
26
|
+
<br/>
|
|
19
27
|
|
|
20
|
-
|
|
28
|
+
## 两大支柱
|
|
29
|
+
|
|
30
|
+
Maestro-Flow 建立在两个相互增强的系统之上:
|
|
31
|
+
|
|
32
|
+
```
|
|
33
|
+
┌─────────────────────────────────────┐
|
|
34
|
+
│ Maestro-Flow │
|
|
35
|
+
│ │
|
|
36
|
+
┌──────────────┴──────────────┐ ┌──────────────────┴───────────────┐
|
|
37
|
+
│ 工作流编排 │ │ 知识系统 │
|
|
38
|
+
│ │ │ │
|
|
39
|
+
│ 意图路由 │ │ 知识图谱 (SQLite) │
|
|
40
|
+
│ └─ 40+ 链类型 │ │ └─ 代码 + 知识统一存储 │
|
|
41
|
+
│ Ralph 决策引擎 │ │ Spec 注入 (Hooks) │
|
|
42
|
+
│ └─ 11 状态 FSM │ │ └─ 自动注入 agent 提示词 │
|
|
43
|
+
│ 质量管线 │ │ Wiki + BM25 搜索 │
|
|
44
|
+
│ └─ verify → review → test│ │ └─ 反向链接 + 健康评分 │
|
|
45
|
+
│ 多智能体调度 │ │ 学习循环 │
|
|
46
|
+
│ └─ Claude, Gemini, Codex │ │ └─ 复盘 → 持久化 → 注入 │
|
|
47
|
+
│ │ │ │
|
|
48
|
+
└─────────────┬───────────────┘ └──────────────────┬───────────────┘
|
|
49
|
+
│ ▲ │ ▲
|
|
50
|
+
│ │ 知识注入 │ │
|
|
51
|
+
│ └──────────────┘ │
|
|
52
|
+
│ 执行结果 │
|
|
53
|
+
└──────────────────────────────────────┘
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
**工作流产生知识,知识改善未来的工作流。** Agent 从每次会话中学习,将发现持久化为 spec 和 knowhow,未来的 agent 通过 hook 注入自动获取这些上下文 — 形成自增强循环。
|
|
21
57
|
|
|
22
58
|
---
|
|
23
59
|
|
|
@@ -28,19 +64,21 @@ npm install -g maestro-flow
|
|
|
28
64
|
maestro install
|
|
29
65
|
```
|
|
30
66
|
|
|
31
|
-
**前置条件**:Node.js
|
|
67
|
+
**前置条件**:Node.js ≥ 18,Claude Code CLI。可选:Codex CLI、Gemini CLI 用于多智能体工作流。
|
|
32
68
|
|
|
33
69
|
---
|
|
34
70
|
|
|
35
71
|
## 快速开始
|
|
36
72
|
|
|
37
|
-
|
|
73
|
+
### Ralph 引擎
|
|
74
|
+
|
|
75
|
+
**`/maestro-ralph`** 是主推入口 — 闭环生命周期引擎,自动读取项目状态,推断你在开发生命周期中的位置,构建自适应命令链:
|
|
38
76
|
|
|
39
77
|
```bash
|
|
40
78
|
/maestro-ralph "实现基于 OAuth2 的用户认证,带 refresh token"
|
|
41
79
|
```
|
|
42
80
|
|
|
43
|
-
Ralph
|
|
81
|
+
Ralph 自动判断你在哪个阶段(brainstorm → plan → execute → verify → review → test → milestone),构建相应命令链。关键检查点的 decision 节点根据实际结果,动态插入 debug → fix → retry 循环。
|
|
44
82
|
|
|
45
83
|
```bash
|
|
46
84
|
/maestro-ralph status # 查看会话进度
|
|
@@ -54,92 +92,169 @@ Ralph 自动判断你在生命周期中的位置(brainstorm → blueprint →
|
|
|
54
92
|
|------|---------|
|
|
55
93
|
| `/maestro "..."` | 描述意图,AI 自动路由最优命令链 |
|
|
56
94
|
| `/maestro-quick` | 快速修复、小功能(analyze → plan → execute) |
|
|
57
|
-
| `/maestro-*` | 逐步执行:
|
|
95
|
+
| `/maestro-*` | 逐步执行:brainstorm、blueprint、analyze、plan、execute、verify |
|
|
58
96
|
|
|
59
97
|
---
|
|
60
98
|
|
|
61
|
-
##
|
|
99
|
+
## 工作流编排
|
|
62
100
|
|
|
63
|
-
###
|
|
101
|
+
### 自适应生命周期引擎
|
|
64
102
|
|
|
65
|
-
|
|
103
|
+
Ralph 是一个 11 状态有限状态机,**只做决策,不做执行**。它读取项目状态,推断生命周期位置,构建带质量门的命令链,将执行交给 `maestro-ralph-execute`。在每个 decision 节点(`◆`),Ralph 评估实际结果并决定:继续前进,还是插入 debug → fix → retry 循环。
|
|
66
104
|
|
|
67
105
|
```
|
|
68
106
|
brainstorm → blueprint(可选) → init → analyze(宏观) → roadmap(可选) → analyze(微观) → plan → execute → verify
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
107
|
+
◆ decision
|
|
108
|
+
review ─── ◆ ─── test ─── ◆ ─── milestone-audit → milestone-complete
|
|
109
|
+
◆ → 下一里程碑
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
**三种质量模式**控制质量深度:
|
|
113
|
+
|
|
114
|
+
| 模式 | 管线 | 适用场景 |
|
|
115
|
+
|------|------|---------|
|
|
116
|
+
| `full` | verify → business-test → review → test-gen → test | 生产环境、安全关键代码 |
|
|
117
|
+
| `standard` | verify → review → test | 默认,平衡质量 |
|
|
118
|
+
| `quick` | verify → CLI-review | 原型开发、快速修复 |
|
|
119
|
+
|
|
120
|
+
### 意图驱动路由
|
|
121
|
+
|
|
122
|
+
你不需要编写 pipeline YAML。用自然语言描述意图,Maestro 将其分类到 **40+ 链类型**中,每种都是预组合的命令序列。同一意图在不同项目状态下产生不同的链:
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
/maestro "添加用户个人资料页"
|
|
126
|
+
# → 新项目: brainstorm → blueprint → analyze → plan → execute → verify
|
|
127
|
+
# → 已有项目: analyze → plan → execute → verify
|
|
128
|
+
# → 快速修复: plan → execute → verify
|
|
78
129
|
```
|
|
79
130
|
|
|
80
|
-
|
|
131
|
+
### 分层命令拓扑
|
|
132
|
+
|
|
133
|
+
命令按四层组织:
|
|
134
|
+
|
|
135
|
+
| 层级 | 用途 | 命令 |
|
|
136
|
+
|------|------|------|
|
|
137
|
+
| **起源层** | 发散创意,收敛方向 | brainstorm、blueprint |
|
|
138
|
+
| **理解层** | 探索范围(宏观)+ 深入研究(微观) | analyze(双模式) |
|
|
139
|
+
| **编排层** | 组织为里程碑和阶段 | roadmap |
|
|
140
|
+
| **执行层** | 计划、实现、验证 | plan、execute、verify、review、test |
|
|
81
141
|
|
|
82
|
-
|
|
142
|
+
6 条规范路径(A–F)覆盖从全新项目到单行修复的所有场景。
|
|
83
143
|
|
|
84
|
-
|
|
144
|
+
### 多智能体调度
|
|
85
145
|
|
|
86
|
-
|
|
87
|
-
2. **business-test** — PRD 前向业务测试:需求追溯、fixture 生成、验收标准多层执行
|
|
88
|
-
3. **review** — 多维度代码审查:正确性、可读性、性能、安全、测试、架构
|
|
89
|
-
4. **test-gen** — 覆盖率缺口分析 + 自动测试生成(TDD/E2E 分类,L0-L3 渐进层)
|
|
90
|
-
5. **test** — 交互式 UAT:探索性测试,会话持久化,缺口闭环
|
|
146
|
+
Maestro 通过四种可组合的编排模式协调 **Claude Code、Codex、Gemini、Qwen、OpenCode**:
|
|
91
147
|
|
|
92
|
-
|
|
148
|
+
| 模式 | 工作方式 |
|
|
149
|
+
|------|---------|
|
|
150
|
+
| **Delegate** | 通过 `maestro delegate` 派发到任意 CLI 工具,SQLite 任务中介管理异步执行,支持消息注入和链式调用 |
|
|
151
|
+
| **Team** | 协调器-工人架构 — 协调器生成角色规格,并行派生 `team-worker` agent,由常驻质量观察者监督 |
|
|
152
|
+
| **Wave** | 任务拓扑排序为依赖波次,波次内独立任务并行执行 |
|
|
153
|
+
| **Swarm** | ACO 蚁群驱动的多智能体探索,信息素引导收敛 |
|
|
93
154
|
|
|
94
|
-
|
|
155
|
+
这些模式可以**组合**:团队协调器可将子任务委托给不同的 LLM 后端,波次执行并行化独立工作,仪表盘提供实时监控 — 所有模式共享中介和消息总线作为协调原语。
|
|
95
156
|
|
|
96
|
-
|
|
157
|
+
---
|
|
97
158
|
|
|
98
|
-
|
|
159
|
+
## 知识系统
|
|
99
160
|
|
|
100
|
-
###
|
|
161
|
+
### 知识图谱
|
|
101
162
|
|
|
102
|
-
|
|
163
|
+
SQLite 支撑的统一图数据库,同时存储**代码结构**(函数、类、调用链,通过 tree-sitter 提取)和**项目知识**(spec、knowhow、领域术语、issue),合并在一个可查询的结构中。
|
|
103
164
|
|
|
104
165
|
```bash
|
|
105
|
-
maestro
|
|
106
|
-
maestro
|
|
107
|
-
maestro
|
|
166
|
+
maestro kg search <symbol> # 查找节点
|
|
167
|
+
maestro kg context <node> # 获取上下文
|
|
168
|
+
maestro kg callers <function> # 追溯调用链
|
|
169
|
+
maestro kg callees <function> # 追溯依赖
|
|
108
170
|
```
|
|
109
171
|
|
|
110
|
-
###
|
|
172
|
+
### Spec 注入
|
|
173
|
+
|
|
174
|
+
项目规则(编码规范、架构约束、质量标准)以带关键词标签的 `<spec-entry>` 格式存储。**Hook 自动将相关 spec 注入每个 agent 的提示词** — agent 无需手动加载即可获得项目专属规则。
|
|
175
|
+
|
|
176
|
+
### 自增强学习循环
|
|
177
|
+
|
|
178
|
+
```
|
|
179
|
+
Agent 执行任务
|
|
180
|
+
→ 发现模式/陷阱/决策
|
|
181
|
+
→ 持久化为 spec 条目或 knowhow 文档
|
|
182
|
+
→ Hook 系统索引新知识
|
|
183
|
+
→ 未来 agent 通过提示词注入自动获取
|
|
184
|
+
→ 更好的执行 → 更多发现 → ...
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
四个学习工具驱动这个循环:`learn-retro`(复盘)、`learn-follow`(模式学习)、`learn-decompose`(架构拆解)、`learn-investigate`(深度探究)。
|
|
188
|
+
|
|
189
|
+
### Wiki 与搜索
|
|
190
|
+
|
|
191
|
+
WikiIndexer 遍历 `.workflow/` 目录,解析 frontmatter,构建反向链接图,并创建 **BM25 倒排索引**用于全文搜索 — 覆盖所有项目知识:spec、knowhow、issue 以及 KG 节点的虚拟条目。
|
|
111
192
|
|
|
112
|
-
|
|
193
|
+
---
|
|
194
|
+
|
|
195
|
+
## Issue 闭环
|
|
113
196
|
|
|
114
|
-
|
|
197
|
+
Issue 不仅是工单,更是自修复管线:
|
|
198
|
+
|
|
199
|
+
```
|
|
200
|
+
discover → analyze → plan → execute → close
|
|
201
|
+
▲ │
|
|
202
|
+
└────── 质量命令自动创建 ──────────────┘
|
|
203
|
+
```
|
|
115
204
|
|
|
116
|
-
|
|
205
|
+
质量命令(review、test、verify)自动为发现的问题创建 Issue,修复代码回流到阶段管线。
|
|
117
206
|
|
|
118
207
|
---
|
|
119
208
|
|
|
120
|
-
##
|
|
209
|
+
## 可视化仪表盘
|
|
121
210
|
|
|
122
|
-
|
|
123
|
-
|------|------|------|------|
|
|
124
|
-
| **核心工作流** | 19 | `maestro-*` | 全生命周期 — ralph、init、brainstorm、blueprint、analyze、roadmap、plan、execute、verify、milestones、overlays |
|
|
125
|
-
| **管理** | 12 | `manage-*` | Issue 生命周期、代码库文档、知识捕获、记忆管理、状态 |
|
|
126
|
-
| **质量** | 9 | `quality-*` | review、test、debug、test-gen、integration-test、business-test、refactor、sync |
|
|
127
|
-
| **学习** | 5 | `learn-*` | 复盘、跟读、模式拆解、探究、多视角 |
|
|
128
|
-
| **规范** | 3 | `spec-*` | setup、add、load |
|
|
129
|
-
| **知识图谱** | 2 | `wiki-*` | 连接发现、知识摘要 |
|
|
211
|
+
实时仪表盘 `http://127.0.0.1:3001` — Kanban 看板、甘特时间线、可排序表格、指挥中心。在 Issue 卡片上选择智能体,一键派发。
|
|
130
212
|
|
|
131
|
-
|
|
213
|
+
```bash
|
|
214
|
+
maestro serve # 启动 Web 仪表盘
|
|
215
|
+
maestro view # 终端 TUI 替代方案
|
|
216
|
+
maestro command-help # 交互式命令参考(别名: ch)
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
基于 React 19、Zustand、Tailwind CSS 4、Framer Motion、Hono、WebSocket 构建。
|
|
132
220
|
|
|
133
221
|
---
|
|
134
222
|
|
|
135
|
-
##
|
|
223
|
+
## 项目概览
|
|
224
|
+
|
|
225
|
+
| 指标 | 数量 |
|
|
226
|
+
|------|------|
|
|
227
|
+
| 源文件 (TypeScript) | 446 |
|
|
228
|
+
| 代码行数 | ~111,000 |
|
|
229
|
+
| 斜杠命令 | 64 |
|
|
230
|
+
| 工作流定义 | 115 |
|
|
231
|
+
| 技能包 | 45 |
|
|
232
|
+
| Agent 定义 | 23 |
|
|
233
|
+
| CLI 命令 | 32 |
|
|
234
|
+
| 模板 | 92 |
|
|
235
|
+
| 指南(双语) | 66 |
|
|
236
|
+
|
|
237
|
+
### 技术栈
|
|
238
|
+
|
|
239
|
+
| 层级 | 技术 |
|
|
240
|
+
|------|------|
|
|
241
|
+
| CLI | Commander.js, TypeScript, ESM |
|
|
242
|
+
| MCP | @modelcontextprotocol/sdk (stdio) |
|
|
243
|
+
| 知识图谱 | better-sqlite3, Drizzle ORM, web-tree-sitter |
|
|
244
|
+
| 前端 | React 19, Zustand, Tailwind CSS 4, Framer Motion, Radix UI |
|
|
245
|
+
| 后端 | Hono, WebSocket, SSE |
|
|
246
|
+
| 智能体 | Claude Agent SDK, Codex CLI, Gemini CLI, OpenCode |
|
|
247
|
+
| 构建 | Vite 6, TypeScript 5.7, Vitest |
|
|
248
|
+
|
|
249
|
+
### 架构
|
|
136
250
|
|
|
137
251
|
```
|
|
138
252
|
maestro/
|
|
139
253
|
├── bin/ # CLI 入口
|
|
140
254
|
├── src/ # 核心 CLI (Commander.js + MCP SDK)
|
|
141
|
-
│ ├── commands/ #
|
|
255
|
+
│ ├── commands/ # 32 个 CLI 命令
|
|
142
256
|
│ ├── mcp/ # MCP 服务器 (stdio 传输)
|
|
257
|
+
│ ├── graph/ # 知识图谱 (SQLite + tree-sitter)
|
|
143
258
|
│ └── core/ # 工具注册、扩展加载器
|
|
144
259
|
├── dashboard/ # 实时 Web 仪表盘
|
|
145
260
|
│ └── src/
|
|
@@ -147,38 +262,41 @@ maestro/
|
|
|
147
262
|
│ ├── server/ # Hono API + WebSocket + SSE
|
|
148
263
|
│ └── shared/ # 共享类型
|
|
149
264
|
├── .claude/
|
|
150
|
-
│ ├── commands/ #
|
|
151
|
-
│
|
|
152
|
-
|
|
153
|
-
├──
|
|
265
|
+
│ ├── commands/ # 64 个斜杠命令 (.md)
|
|
266
|
+
│ ├── agents/ # 23 个 Agent 定义 (.md)
|
|
267
|
+
│ └── skills/ # 45 个技能包
|
|
268
|
+
├── workflows/ # 115 个工作流定义 (.md)
|
|
269
|
+
├── templates/ # 92 个 JSON 模板
|
|
154
270
|
└── extensions/ # 插件系统
|
|
155
271
|
```
|
|
156
272
|
|
|
157
|
-
| 层级 | 技术 |
|
|
158
|
-
|------|------|
|
|
159
|
-
| CLI | Commander.js, TypeScript, ESM |
|
|
160
|
-
| MCP | @modelcontextprotocol/sdk (stdio) |
|
|
161
|
-
| 前端 | React 19, Zustand, Tailwind CSS 4, Framer Motion, Radix UI |
|
|
162
|
-
| 后端 | Hono, WebSocket, SSE |
|
|
163
|
-
| 智能体 | Claude Agent SDK, Codex CLI, Gemini CLI, OpenCode |
|
|
164
|
-
| 构建 | Vite 6, TypeScript 5.7, Vitest |
|
|
165
|
-
|
|
166
273
|
---
|
|
167
274
|
|
|
168
275
|
## 文档
|
|
169
276
|
|
|
170
|
-
|
|
171
|
-
- **[
|
|
172
|
-
- **[
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
- **[
|
|
176
|
-
- **[
|
|
177
|
-
- **[
|
|
178
|
-
- **[
|
|
179
|
-
- **[
|
|
180
|
-
|
|
181
|
-
|
|
277
|
+
**快速入门**
|
|
278
|
+
- **[快速开始指南](guide/quick-start-guide.md)** — 安装、第一个工作流、核心概念
|
|
279
|
+
- **[Maestro Ralph 指南](guide/maestro-ralph-guide.md)** — 自适应生命周期引擎、decision 节点、质量模式
|
|
280
|
+
|
|
281
|
+
**工作流**
|
|
282
|
+
- **[命令使用指南](guide/command-usage-guide.md)** — 全部 64 个命令,含工作流图表和管线衔接
|
|
283
|
+
- **[CLI 命令参考](guide/cli-commands-guide.md)** — 全部 32 个终端命令
|
|
284
|
+
- **[工作流结构指南](guide/workflow-structure-guide.md)** — 命令拓扑、链组合
|
|
285
|
+
- **[质量管线指南](guide/quality-pipeline-guide.md)** — verify、review、test 管线
|
|
286
|
+
- **[Maestro 协调器指南](guide/maestro-coordinator-guide.md)** — 多智能体协调模式
|
|
287
|
+
|
|
288
|
+
**知识系统**
|
|
289
|
+
- **[知识管理指南](guide/knowledge-management-guide.md)** — KG、spec、knowhow、wiki
|
|
290
|
+
- **[Spec 系统指南](guide/spec-system-guide.md)** — spec 条目、关键词加载、验证 Hook
|
|
291
|
+
- **[Hook 系统指南](guide/hooks-guide.md)** — 17 个 Hook、Spec 注入、上下文预算
|
|
292
|
+
- **[学习工具指南](guide/learn-tools-guide.md)** — 复盘、跟读、拆解、探究
|
|
293
|
+
|
|
294
|
+
**进阶**
|
|
295
|
+
- **[Delegate 异步执行指南](guide/delegate-async-guide.md)** — 多 CLI 委派、消息注入、链式调用
|
|
296
|
+
- **[Overlay 系统指南](guide/overlay-guide.md)** — 非侵入式命令扩展
|
|
297
|
+
- **[Worktree 并行开发指南](guide/worktree-guide.md)** — 里程碑级并行开发
|
|
298
|
+
- **[MCP 工具参考](guide/mcp-tools-guide.md)** — 全部 9 个 MCP 端点工具
|
|
299
|
+
- **[Collab 协作指南](guide/team-lite-guide.md)** — 2-8 人团队协作
|
|
182
300
|
|
|
183
301
|
---
|
|
184
302
|
|
|
@@ -186,6 +304,7 @@ maestro/
|
|
|
186
304
|
|
|
187
305
|
- **[GET SHIT DONE](https://github.com/gsd-build/get-shit-done)** by TACHES — 规格驱动开发模型和上下文工程理念。
|
|
188
306
|
- **[Claude-Code-Workflow](https://github.com/catlog22/Claude-Code-Workflow)** — 前身项目,开创了多 CLI 编排和 skill 路由工作流。
|
|
307
|
+
- **[Impeccable](https://github.com/pbakaus/impeccable)** by [@pbakaus](https://github.com/pbakaus) — UI 设计技能,集成为 `maestro-impeccable`。基于 [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) 许可。
|
|
189
308
|
|
|
190
309
|
## 贡献者
|
|
191
310
|
|
|
@@ -33,11 +33,14 @@ export function buildGraph(index) {
|
|
|
33
33
|
const hit = titleIndex.get(target.toLowerCase());
|
|
34
34
|
return hit ?? null;
|
|
35
35
|
};
|
|
36
|
+
const fwdSets = new Map();
|
|
36
37
|
const pushFwd = (source, targetId) => {
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
38
|
+
let s = fwdSets.get(source);
|
|
39
|
+
if (!s) {
|
|
40
|
+
s = new Set();
|
|
41
|
+
fwdSets.set(source, s);
|
|
42
|
+
}
|
|
43
|
+
s.add(targetId);
|
|
41
44
|
};
|
|
42
45
|
for (const d of index.entries) {
|
|
43
46
|
// `related` frontmatter
|
|
@@ -69,6 +72,8 @@ export function buildGraph(index) {
|
|
|
69
72
|
}
|
|
70
73
|
}
|
|
71
74
|
}
|
|
75
|
+
for (const [k, v] of fwdSets)
|
|
76
|
+
forwardLinks[k] = [...v];
|
|
72
77
|
return {
|
|
73
78
|
forwardLinks,
|
|
74
79
|
backlinks: index.backlinks,
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"graph-analysis.js","sourceRoot":"","sources":["../../../../../src/server/wiki/graph-analysis.ts"],"names":[],"mappings":"AAEA,2EAA2E;AAC3E,mEAAmE;AACnE,wDAAwD;AACxD,MAAM,gBAAgB,GAA2B;IAC/C,UAAU,EAAE,GAAG;IACf,OAAO,EAAE,GAAG;IACZ,KAAK,EAAE,GAAG;IACV,OAAO,EAAE,GAAG;IACZ,UAAU,EAAE,GAAG;IACf,OAAO,EAAE,GAAG;IACZ,QAAQ,EAAE,GAAG;IACb,IAAI,EAAE,GAAG;IACT,UAAU,EAAE,GAAG;IACf,QAAQ,EAAE,GAAG;IACb,UAAU,EAAE,GAAG;IACf,KAAK,EAAE,GAAG;IACV,UAAU,EAAE,GAAG;CAChB,CAAC;AAmCF,MAAM,OAAO,GAAG,mBAAmB,CAAC;AAEpC;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,KAAgB;IACzC,MAAM,YAAY,GAA6B,EAAE,CAAC;IAClD,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,MAAM,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC7C,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO;QAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IAE3E,MAAM,OAAO,GAAG,CAAC,MAAc,EAAiB,EAAE;QAChD,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC;YAAE,OAAO,MAAM,CAAC;QACtC,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;QACjD,OAAO,GAAG,IAAI,IAAI,CAAC;IACrB,CAAC,CAAC;IAEF,MAAM,OAAO,GAAG,CAAC,MAAc,EAAE,QAAgB,EAAE,EAAE;QACnD,IAAI,CAAC,
|
|
1
|
+
{"version":3,"file":"graph-analysis.js","sourceRoot":"","sources":["../../../../../src/server/wiki/graph-analysis.ts"],"names":[],"mappings":"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"}
|
|
@@ -1,20 +1,23 @@
|
|
|
1
1
|
import type { WikiEntry } from './wiki-types.js';
|
|
2
2
|
type FieldName = 'title' | 'summary' | 'tags' | 'body';
|
|
3
|
+
/** @deprecated Legacy flat posting — kept for test backward compat only. */
|
|
3
4
|
export interface Posting {
|
|
4
5
|
docId: string;
|
|
5
6
|
tf: number;
|
|
6
7
|
}
|
|
7
8
|
export type FieldConfigKey = 'default' | 'kg' | 'scratch';
|
|
8
9
|
export interface InvertedIndex {
|
|
10
|
+
/** @deprecated Legacy flat postings — not used by BM25F scoring. */
|
|
9
11
|
postings: Map<string, Posting[]>;
|
|
12
|
+
/** @deprecated Legacy flat doc lengths — not used by BM25F scoring. */
|
|
10
13
|
docLengths: Map<string, number>;
|
|
14
|
+
/** @deprecated Legacy flat avg doc length — not used by BM25F scoring. */
|
|
11
15
|
avgDocLength: number;
|
|
12
16
|
totalDocs: number;
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
_docConfigKeys?: Map<string, FieldConfigKey>;
|
|
17
|
+
fieldPostings: Map<string, FieldPosting[]>;
|
|
18
|
+
fieldLengths: Map<string, FieldLengths>;
|
|
19
|
+
avgFieldLengths: FieldLengths;
|
|
20
|
+
docConfigKeys: Map<string, FieldConfigKey>;
|
|
18
21
|
}
|
|
19
22
|
export interface SearchResult {
|
|
20
23
|
docId: string;
|
|
@@ -36,6 +36,10 @@ const CJK_RUN = /[一-鿿㐀-䶿]+/g;
|
|
|
36
36
|
const HAS_CJK = /[一-鿿㐀-䶿]/;
|
|
37
37
|
function cjkNgrams(run) {
|
|
38
38
|
const out = [];
|
|
39
|
+
if (run.length === 1) {
|
|
40
|
+
out.push(run);
|
|
41
|
+
return out;
|
|
42
|
+
}
|
|
39
43
|
for (let n = 2; n <= 3; n++) {
|
|
40
44
|
if (run.length < n)
|
|
41
45
|
break;
|
|
@@ -165,8 +169,9 @@ export function buildInvertedIndex(entries) {
|
|
|
165
169
|
},
|
|
166
170
|
});
|
|
167
171
|
}
|
|
168
|
-
|
|
169
|
-
const
|
|
172
|
+
let flatTotal = 0;
|
|
173
|
+
for (const c of flatTermCounts.values())
|
|
174
|
+
flatTotal += c;
|
|
170
175
|
docLengths.set(entry.id, flatTotal);
|
|
171
176
|
totalLength += flatTotal;
|
|
172
177
|
for (const [term, tf] of flatTermCounts) {
|
|
@@ -190,10 +195,10 @@ export function buildInvertedIndex(entries) {
|
|
|
190
195
|
docLengths,
|
|
191
196
|
avgDocLength: totalDocs === 0 ? 0 : totalLength / totalDocs,
|
|
192
197
|
totalDocs,
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
198
|
+
fieldPostings,
|
|
199
|
+
fieldLengths,
|
|
200
|
+
avgFieldLengths,
|
|
201
|
+
docConfigKeys,
|
|
197
202
|
};
|
|
198
203
|
}
|
|
199
204
|
// ---------------------------------------------------------------------------
|
|
@@ -204,13 +209,7 @@ export function searchBM25(index, query, limit = 50, credibilityFactors) {
|
|
|
204
209
|
if (terms.length === 0 || index.totalDocs === 0)
|
|
205
210
|
return [];
|
|
206
211
|
const fetchLimit = (credibilityFactors && credibilityFactors.size > 0) ? limit * 2 : limit;
|
|
207
|
-
|
|
208
|
-
if (index._fieldPostings && index._fieldLengths && index._avgFieldLengths) {
|
|
209
|
-
results = searchBM25F(index, terms, fetchLimit);
|
|
210
|
-
}
|
|
211
|
-
else {
|
|
212
|
-
results = searchBM25Flat(index, terms, fetchLimit);
|
|
213
|
-
}
|
|
212
|
+
const results = searchBM25F(index, terms, fetchLimit);
|
|
214
213
|
if (credibilityFactors && credibilityFactors.size > 0) {
|
|
215
214
|
for (const r of results) {
|
|
216
215
|
const factor = credibilityFactors.get(r.docId) ?? 1.0;
|
|
@@ -221,13 +220,14 @@ export function searchBM25(index, query, limit = 50, credibilityFactors) {
|
|
|
221
220
|
return results.slice(0, limit);
|
|
222
221
|
}
|
|
223
222
|
function searchBM25F(index, terms, limit) {
|
|
224
|
-
const fp = index.
|
|
225
|
-
const fl = index.
|
|
226
|
-
const afl = index.
|
|
227
|
-
const dck = index.
|
|
223
|
+
const fp = index.fieldPostings;
|
|
224
|
+
const fl = index.fieldLengths;
|
|
225
|
+
const afl = index.avgFieldLengths;
|
|
226
|
+
const dck = index.docConfigKeys;
|
|
228
227
|
const fields = ['title', 'summary', 'tags', 'body'];
|
|
228
|
+
const uniqueTerms = [...new Set(terms)];
|
|
229
229
|
const scores = new Map();
|
|
230
|
-
for (const term of
|
|
230
|
+
for (const term of uniqueTerms) {
|
|
231
231
|
const postings = fp.get(term);
|
|
232
232
|
if (!postings || postings.length === 0)
|
|
233
233
|
continue;
|
|
@@ -237,15 +237,16 @@ function searchBM25F(index, terms, limit) {
|
|
|
237
237
|
const docFL = fl.get(docId);
|
|
238
238
|
if (!docFL)
|
|
239
239
|
continue;
|
|
240
|
-
const docConfigs = FIELD_CONFIG_MAP[dck
|
|
241
|
-
// BM25F: compute weighted pseudo-TF across all fields
|
|
240
|
+
const docConfigs = FIELD_CONFIG_MAP[dck.get(docId) ?? 'default'];
|
|
242
241
|
let tfTilde = 0;
|
|
243
242
|
for (const f of fields) {
|
|
244
243
|
const boost = docConfigs[f].boost;
|
|
245
244
|
const b = docConfigs[f].b;
|
|
246
245
|
if (boost === 0 || fieldTfs[f] === 0)
|
|
247
246
|
continue;
|
|
248
|
-
|
|
247
|
+
if (afl[f] === 0)
|
|
248
|
+
continue;
|
|
249
|
+
const norm = 1 - b + b * (docFL[f] / afl[f]);
|
|
249
250
|
tfTilde += boost * (fieldTfs[f] / (norm || 1));
|
|
250
251
|
}
|
|
251
252
|
const termScore = idf * ((tfTilde * (BM25_K1 + 1)) / (tfTilde + BM25_K1));
|
|
@@ -258,25 +259,4 @@ function searchBM25F(index, terms, limit) {
|
|
|
258
259
|
ranked.sort((a, b) => b.score - a.score || a.docId.localeCompare(b.docId));
|
|
259
260
|
return ranked.slice(0, limit);
|
|
260
261
|
}
|
|
261
|
-
function searchBM25Flat(index, terms, limit) {
|
|
262
|
-
const scores = new Map();
|
|
263
|
-
for (const term of terms) {
|
|
264
|
-
const postings = index.postings.get(term);
|
|
265
|
-
if (!postings || postings.length === 0)
|
|
266
|
-
continue;
|
|
267
|
-
const df = postings.length;
|
|
268
|
-
const idf = Math.log(1 + (index.totalDocs - df + 0.5) / (df + 0.5));
|
|
269
|
-
for (const { docId, tf } of postings) {
|
|
270
|
-
const dl = index.docLengths.get(docId) ?? 0;
|
|
271
|
-
const denom = tf + BM25_K1 * (1 - BM25_K1 + (BM25_K1 * dl) / (index.avgDocLength || 1));
|
|
272
|
-
const termScore = idf * ((tf * (BM25_K1 + 1)) / (denom || 1));
|
|
273
|
-
scores.set(docId, (scores.get(docId) ?? 0) + termScore);
|
|
274
|
-
}
|
|
275
|
-
}
|
|
276
|
-
const ranked = [];
|
|
277
|
-
for (const [docId, score] of scores)
|
|
278
|
-
ranked.push({ docId, score });
|
|
279
|
-
ranked.sort((a, b) => b.score - a.score || a.docId.localeCompare(b.docId));
|
|
280
|
-
return ranked.slice(0, limit);
|
|
281
|
-
}
|
|
282
262
|
//# sourceMappingURL=search.js.map
|