Skip to content

Commit 3acfd0b

Browse files
CopilotKuaaMU
Copilot
and
KuaaMU
committed
feat: Phase 2 - ESLint/Prettier, DomainRouter, SwarmCommit/SwarmChallenge tests, CI refactor
Co-authored-by: KuaaMU <138859253+KuaaMU@users.noreply.github.com>
1 parent f94e108 commit 3acfd0b

21 files changed

Lines changed: 2011 additions & 389 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 13 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,13 @@ concurrency:
1010
group: ci-${{ github.ref }}
1111
cancel-in-progress: true
1212

13+
permissions:
14+
contents: read
15+
1316
jobs:
14-
# ─── Install ────────────────────────────────────────────────────────────────
15-
install:
16-
name: Install dependencies
17+
# ─── Lint ───────────────────────────────────────────────────────────────────
18+
lint:
19+
name: Lint
1720
runs-on: ubuntu-latest
1821
steps:
1922
- uses: actions/checkout@v4
@@ -27,47 +30,13 @@ jobs:
2730
- name: Install
2831
run: npm ci
2932

30-
- name: Cache node_modules
31-
uses: actions/cache@v4
32-
with:
33-
path: |
34-
node_modules
35-
packages/**/node_modules
36-
key: node-modules-${{ hashFiles('package-lock.json') }}
37-
38-
# ─── Typecheck ──────────────────────────────────────────────────────────────
39-
typecheck:
40-
name: Type-check
41-
runs-on: ubuntu-latest
42-
needs: install
43-
steps:
44-
- uses: actions/checkout@v4
45-
46-
- name: Setup Node.js
47-
uses: actions/setup-node@v4
48-
with:
49-
node-version: "20"
50-
cache: "npm"
51-
52-
- name: Restore node_modules
53-
uses: actions/cache@v4
54-
with:
55-
path: |
56-
node_modules
57-
packages/**/node_modules
58-
key: node-modules-${{ hashFiles('package-lock.json') }}
59-
60-
- name: Install (if cache miss)
61-
run: npm ci
62-
63-
- name: Build TypeScript packages (excluding contracts & dashboard)
64-
run: npx turbo run build --filter='!@swarmmind/contracts' --filter='!@swarmmind/dashboard'
33+
- name: Lint TypeScript
34+
run: npm run lint
6535

66-
# ─── Test ───────────────────────────────────────────────────────────────────
36+
# ─── Typecheck + Test ───────────────────────────────────────────────────────
6737
test:
68-
name: Unit tests
38+
name: Typecheck & Test
6939
runs-on: ubuntu-latest
70-
needs: typecheck
7140
steps:
7241
- uses: actions/checkout@v4
7342

@@ -77,19 +46,12 @@ jobs:
7746
node-version: "20"
7847
cache: "npm"
7948

80-
- name: Restore node_modules
81-
uses: actions/cache@v4
82-
with:
83-
path: |
84-
node_modules
85-
packages/**/node_modules
86-
key: node-modules-${{ hashFiles('package-lock.json') }}
87-
88-
- name: Install (if cache miss)
49+
- name: Install
8950
run: npm ci
9051

91-
- name: Build (tests depend on dist/)
52+
- name: Build TypeScript packages (excluding contracts & dashboard)
9253
run: npx turbo run build --filter='!@swarmmind/contracts' --filter='!@swarmmind/dashboard'
9354

9455
- name: Run tests
9556
run: npx vitest run --reporter=verbose
57+

‎.prettierrc.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"semi": true,
3+
"singleQuote": false,
4+
"tabWidth": 2,
5+
"trailingComma": "all",
6+
"printWidth": 100,
7+
"endOfLine": "lf"
8+
}

‎docs/workflow/status-report.md‎

Lines changed: 67 additions & 124 deletions
Original file line numberDiff line numberDiff line change
@@ -8,21 +8,23 @@
88

99
## 执行摘要
1010

11-
本文档记录 SwarmMind v1 工程化任务（Tasks 01–04）的落地进度、遇到的问题及解决方案，供代码 Review 和后续迭代参考。
11+
本文档记录 SwarmMind v1 工程化任务（Tasks 01–08）的落地进度、遇到的问题及解决方案，供代码 Review 和后续迭代参考。
1212

1313
---
1414

1515
## 自审清单
1616

1717
| # | 任务 | 状态 | 备注 |
1818
|---|------|------|------|
19-
| 01 | Monorepo 结构初始化 | ✅ 完成 | npm workspaces + Turborepo（已存在，补充 shared-types） |
19+
| 01 | Monorepo 结构初始化 | ✅ 完成 | npm workspaces + Turborepo |
2020
| 02 | `packages/shared-types/src/protocol.ts` | ✅ 完成 | Domain + EvidencePointer + AgentProposal + ConsensusDecision + Zod schemas |
21-
| 03 | RiskAgent & LiquidityAgent | ✅ 完成 | 已存在于 packages/agents；提供 deterministic test fixtures |
22-
| 04 | 共识引擎（evidenceRoot + decisionHash） | ✅ 完成 | 新增 Merkle root 计算 + schema 扩展 |
23-
| 05 | GitHub Actions CI 工作流 | ✅ 完成 | `.github/workflows/ci.yml`（install → typecheck → test） |
24-
| 06 | 合约 SwarmCommit.sol & SwarmChallenge.sol | ✅ 完成 | 与路线图规范对齐 |
25-
| 07 | 状态汇报文档 | ✅ 完成 | 本文件 |
21+
| 03 | RiskAgent & LiquidityAgent | ✅ 完成 | packages/agents 下完整实现 |
22+
| 04 | 共识引擎（evidenceRoot + decisionHash） | ✅ 完成 | Merkle root 计算 + schema 扩展 |
23+
| 05 | GitHub Actions CI 工作流 | ✅ 完成 | lint + test 两个并行 job |
24+
| 06 | 合约 SwarmCommit.sol & SwarmChallenge.sol | ✅ 完成 | 含 Hardhat 测试（19 新测试用例） |
25+
| 07 | ESLint + Prettier 配置 | ✅ 完成 | eslint.config.mjs + .prettierrc.json；CI lint 步骤通过 |
26+
| 08 | Domain Router | ✅ 完成 | `packages/consensus/src/router.ts`；12 个单元测试全部通过 |
27+
| 09 | 状态汇报文档 | ✅ 完成 | 本文件 |
2628

2729
---
2830

@@ -33,173 +35,114 @@
3335
| 路径 | 说明 |
3436
|------|------|
3537
| `packages/shared-types/package.json` | 新包配置（@swarmmind/shared-types） |
36-
| `packages/shared-types/tsconfig.json` | TypeScript 配置 |
37-
| `packages/shared-types/vitest.config.ts` | 测试配置 |
38-
| `packages/shared-types/src/protocol.ts` | 核心协议类型：Domain, EvidencePointer, AgentProposal, ConsensusDecision + Zod schemas + helpers |
38+
| `packages/shared-types/src/protocol.ts` | 核心协议类型：Domain, EvidencePointer, AgentProposal, ConsensusDecision |
3939
| `packages/shared-types/src/index.ts` | 包公共 API |
4040
| `packages/shared-types/src/__tests__/protocol.test.ts` | 协议类型单元测试 |
4141
| `packages/contracts/contracts/SwarmCommit.sol` | 链上决策承诺合约 |
4242
| `packages/contracts/contracts/SwarmChallenge.sol` | 链上挑战机制合约 |
43-
| `.github/workflows/ci.yml` | CI 工作流（install → typecheck → test） |
43+
| `packages/consensus/src/router.ts` | Domain Router：按 domain 路由提案到独立共识池 |
44+
| `packages/consensus/src/__tests__/router.test.ts` | Domain Router 单元测试（12 用例） |
45+
| `.github/workflows/ci.yml` | CI 工作流（lint + typecheck+test） |
46+
| `eslint.config.mjs` | ESLint v10 flat config |
47+
| `.prettierrc.json` | Prettier 格式化配置 |
4448
| `docs/workflow/status-report.md` | 本文件 |
4549

4650
### 修改文件
4751

4852
| 路径 | 变更内容 |
4953
|------|---------|
50-
| `package.json` | 将 `packages/shared-types` 加入 workspaces |
54+
| `package.json` | 新增 shared-types 到 workspaces；新增 lint/format scripts；新增 ESLint/Prettier devDeps |
5155
| `packages/agents/shared/src/schemas.ts` | 为 `ConsensusResultSchema` 新增 `evidenceRoot` 字段 |
52-
| `packages/consensus/src/engine.ts` | 新增 `buildEvidenceRoot()` 辅助函数，在 `run()` 中计算并输出 `evidenceRoot` |
53-
| `packages/consensus/src/__tests__/engine.test.ts` | 新增 evidenceRoot 相关测试 |
54-
55-
---
56-
57-
## 主要代码片段
58-
59-
### 1. `packages/shared-types/src/protocol.ts` – Domain 枚举
60-
61-
```typescript
62-
export const DomainSchema = z.enum([
63-
"liquidation_risk",
64-
"pool_anomaly",
65-
"cross_venue_spread",
66-
"contract_health",
67-
"news_sentiment",
68-
]);
69-
export type Domain = z.infer<typeof DomainSchema>;
70-
```
71-
72-
### 2. EvidencePointer + AgentProposal Zod Schema
73-
74-
```typescript
75-
export const EvidencePointerSchema = z.object({
76-
type: z.enum(["tx_hash", "block_range", "api_snapshot", "model_artifact"]),
77-
uri: z.string().min(1),
78-
hash: z.string().regex(/^[0-9a-f]{64}$/),
79-
timestamp: z.number().int().positive(),
80-
});
81-
82-
export const AgentProposalSchema = z.object({
83-
proposalId: z.string().min(1),
84-
agentId: z.string().min(1),
85-
domain: DomainSchema,
86-
claim: z.string().min(1),
87-
confidence: z.number().min(0).max(1),
88-
expectedValue: z.number().optional(),
89-
riskScore: z.number().min(0).max(100).optional(),
90-
evidence: z.array(EvidencePointerSchema),
91-
traceHash: z.string().regex(/^[0-9a-f]{64}$/),
92-
createdAt: z.number().int().positive(),
93-
});
94-
```
95-
96-
### 3. ConsensusDecision – evidenceRoot + decisionHash
97-
98-
```typescript
99-
export const ConsensusDecisionSchema = z.object({
100-
decisionId: z.string().min(1),
101-
domain: DomainSchema,
102-
finalClaim: z.string(),
103-
finalScore: z.number().min(0).max(1),
104-
participants: z.array(z.string().min(1)),
105-
scoreVector: z.record(z.string(), z.number()),
106-
evidenceRoot: z.string().regex(/^[0-9a-f]{64}$/),
107-
decisionHash: z.string().regex(/^[0-9a-f]{64}$/),
108-
createdAt: z.number().int().positive(),
109-
});
110-
```
111-
112-
### 4. 共识引擎 – Merkle evidence root
113-
114-
```typescript
115-
function buildEvidenceRoot(evidencePointers: readonly string[]): string {
116-
if (evidencePointers.length === 0)
117-
return createHash("sha256").update("").digest("hex");
118-
119-
let layer = [...evidencePointers]
120-
.sort()
121-
.map(p => createHash("sha256").update(p).digest("hex"));
122-
123-
while (layer.length > 1) {
124-
const next: string[] = [];
125-
for (let i = 0; i < layer.length; i += 2) {
126-
const left = layer[i]!;
127-
const right = layer[i + 1] ?? left;
128-
next.push(createHash("sha256").update(left + right).digest("hex"));
129-
}
130-
layer = next;
131-
}
132-
return layer[0]!;
133-
}
134-
```
56+
| `packages/consensus/src/engine.ts` | 新增 `buildEvidenceRoot()` + `evidenceRoot` 输出 |
57+
| `packages/consensus/src/index.ts` | 导出 DomainRouter + 相关类型 |
58+
| `packages/consensus/src/__tests__/engine.test.ts` | 新增 evidenceRoot 测试 |
59+
| `packages/contracts/test/contracts.test.ts` | 新增 SwarmCommit + SwarmChallenge 测试（19 用例） |
13560

13661
---
13762

13863
## 测试结果
13964

14065
| 指标 | 数值 |
14166
|------|------|
142-
| 测试文件数 | 17 passed（新增 packages/shared-types 测试文件） |
143-
| 测试用例数 | 原 163 + 新增 29（协议类型）+ 2（evidenceRoot）= **192 passed** |
67+
| Vitest 测试文件 | **18 passed** |
68+
| Vitest 测试用例 | **208 passed** |
69+
| Hardhat 合约测试 | **65 passing**（含新增 19 用例） |
14470
| 构建状态 | `turbo build` 全部 8 个 TypeScript 包成功 |
71+
| ESLint | **0 errors**, 91 warnings（console.log 为服务层有意保留） |
14572

14673
---
14774

14875
## CI 状态
14976

150-
GitHub Actions 工作流 `.github/workflows/ci.yml` 已创建，包含以下阶段：
77+
GitHub Actions 工作流 `.github/workflows/ci.yml` 含以下两个并行 job：
15178

152-
1. **install** – `npm ci` 安装全部依赖
153-
2. **typecheck** – `turbo build`（排除 contracts 和 dashboard）
154-
3. **test** – `vitest run`（全量单元测试）
79+
1. **lint** – `npm run lint`（ESLint，0 errors）
80+
2. **test** – `turbo build` → `vitest run`（208 用例）
81+
82+
---
83+
84+
## Domain Router 架构
85+
86+
`DomainRouter`（`packages/consensus/src/router.ts`）将 `AgentProposal` 按 domain 路由到独立的 `ConsensusEngine` 实例：
87+
88+
```
89+
AgentProposals[]
90+
│
91+
▼ resolveDomain(proposal)
92+
┌──────────────────────────────────────────────────────────┐
93+
│ Keyword classifier (fallback) │ explicit .domain field │
94+
└──────────────────────────────────────────────────────────┘
95+
│
96+
▼
97+
┌──────────────────────────────────────────────────────────┐
98+
│ liquidation_risk │ pool_anomaly │ cross_venue_spread │ │
99+
│ contract_health │ news_sentiment │ │
100+
│ ───────────────────────────────────────────────────── │ │
101+
│ each has own ConsensusEngine + ReputationRegistry │ │
102+
└──────────────────────────────────────────────────────────┘
103+
│
104+
▼
105+
Map<RoutableDomain, ConsensusResult>
106+
```
155107

156108
---
157109

158110
## 遇到的问题与解决结果
159111

160112
| # | 问题 | 解决方案 |
161113
|---|------|---------|
162-
| 1 | 仓库使用 npm workspaces + Turborepo，非 pnpm monorepo | 在现有结构基础上补充 `packages/shared-types`，与现有约定保持一致 |
163-
| 2 | 首次运行测试时 vitest 未安装（`npm install` 未执行） | 执行 `npm install` 后全部 163 个测试通过 |
164-
| 3 | `ConsensusResultSchema` 无 `evidenceRoot` 字段，引发 Zod 校验失败 | 在 schema 定义中新增 `evidenceRoot` 为 optional 字段，保持向后兼容 |
114+
| 1 | ESLint v10 不支持 `.eslintrc.json` 格式 | 改用 `eslint.config.mjs`（flat config） |
115+
| 2 | 旧测试文件中有 14 处 unused-import 错误 | 逐一删除无用 import，保持原有测试逻辑不变 |
116+
| 3 | `resolveAIKey` 和 `requireEnv` 在 env.ts 中定义但未被使用 | 删除无引用的函数，避免死代码 |
117+
| 4 | EWMA 测试断言方向错误（0.9 < 1.0 导致 rep 下降） | 修正测试：使用 1.5 outcome 使 rep 上升 |
165118

166119
---
167120

168121
## 剩余待解决问题与建议
169122

170-
### Phase 1 剩余任务（本 PR 未覆盖）
123+
### Phase 1 剩余任务
171124

172125
- [ ] 数据接入层：链上 DEX/lending indexer + 价格 feed 适配
173126
- [ ] Message bus 集成（Redis Streams / NATS）
174127
- [ ] `packages/shared-types` 与 `@swarmmind/shared` 的长期统一策略
175-
- 建议：逐步将 `@swarmmind/shared` 中的 protocol 类型迁移至 `@swarmmind/shared-types`
176128

177-
### Phase 2 待实现
129+
### Phase 2 后续
178130

179-
- [ ] Domain router（按 domain 路由提案到对应共识池）
180-
- [ ] 基准测试（单 agent vs 多 agent 误报率对比）
181-
- [ ] `ConsensusDecision` 与 `ConsensusResult` 的统一（二者有功能重叠）
131+
- [ ] Timeliness factor T_i（较新提案权重加成）
132+
- [ ] 基准测试：单 agent vs 多 agent 误报率对比
133+
- [ ] `ConsensusDecision` 与 `ConsensusResult` 的统一
182134

183135
### 合约部署
184136

185-
- [ ] 补充 `SwarmCommit.sol` 和 `SwarmChallenge.sol` 的 Hardhat 测试
186-
- [ ] 编写部署脚本（已有 `scripts/deploy.ts` 参考）
187137
- [ ] X Layer Testnet 部署验证
138+
- [ ] 手动审批门控 job（production deploy）
188139

189-
### CI 增强建议
190-
191-
- [ ] 增加 `eslint` lint 检查步骤
192-
- [ ] 增加 contracts `hardhat test` 步骤（独立 job）
193-
- [ ] 增加 production 部署的手动审批门控
194-
195-
### Codespace / 远程开发建议
140+
### CI 增强
196141

197-
如在本地环境遇到依赖安装问题（npm 版本差异、网络限制），建议：
198-
199-
1. **GitHub Codespaces** – 仓库已有 `docker-compose.yml`，可直接在 Codespace 中 `docker compose up` 启动所有服务
200-
2. **Node 版本管理** – 建议在仓库根目录添加 `.nvmrc`（内容：`20`）或 `.node-version` 文件，统一开发环境
201-
3. **turbo cache** – CI 中可开启 `TURBO_TOKEN` + `TURBO_TEAM` 远程缓存加速构建
142+
- [ ] Hardhat 合约测试纳入 CI（独立 job）
143+
- [ ] `TURBO_TOKEN` 远程缓存加速
202144

203145
---
204146

205147
*本文档由 Copilot Coding Agent 自动生成，随代码变更同步更新。*
148+

0 commit comments

Comments
 (0)