Skip to content

Commit 3202cf7

Browse files
beihailibeihaili
authored
Merge pull request #227 from beihaili/codex/roadmap-06-ai-native-v1
feat: stabilize AI-native v1 surface
2 parents 485ccdf + 986ffaf commit 3202cf7

19 files changed

Lines changed: 787 additions & 60 deletions

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
- 新增 L2 / 跨链桥风险模拟器 `/labs/l2-risk`，用于本地比较 finality、桥信任假设、消息传递、sequencer 状态和嵌入式桥接 UX 风险。
99
- 新增双语课程 `L2CrossChain/06_BridgeRiskSimulator`、对应 quiz、术语表条目和 AI-native 索引路径。
1010
- 新增 credential architecture tradeoff note，将现有 ERC-721 certificate 明确为学习证书设计方案之一，而非默认生产证书系统。
11+
- 新增 AI-native v1 artifact contract、稳定层验证和变现决策文档，明确本地 MCP 继续保持免费、只读、不执行支付或链上操作。
1112

1213
## [1.0.0] - 2026-02-09
1314

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -152,6 +152,8 @@ Then connect an MCP client and use:
152152

153153
Local MCP tools are read-only. They do not enforce payment, sign transactions, or perform chain operations. x402 fields are reserved metadata for future hosted paid tools.
154154

155+
AI artifacts are maintained as a stable v1 public surface through `artifactContract.version`; see [AI-native v1 stability and monetization decision](docs/strategy/2026-06-26-ai-native-v1-stability-and-monetization.md).
156+
155157
## Tech Stack
156158

157159
- **Frontend:** React 19 + Vite + Tailwind CSS

‎README.zh.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -152,6 +152,8 @@ npm run mcp:web3
152152

153153
本地 MCP 工具保持只读，不执行支付验证、链上签名或链上操作。x402 字段只是为未来远程付费工具预留的元数据。
154154

155+
AI artifacts 通过 `artifactContract.version` 作为稳定 v1 公开接口维护；详见 [AI-native v1 稳定层与变现决策](docs/strategy/2026-06-26-ai-native-v1-stability-and-monetization.md)。
156+
155157
## 技术栈
156158

157159
- **Frontend:** React 19 + Vite + Tailwind CSS

‎ai/content-index.json‎

Lines changed: 81 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,38 @@
11
{
22
"schemaVersion": "2026-05-09",
3-
"generatedAt": "2026-06-25T06:15:17.140Z",
3+
"artifactContract": {
4+
"version": "1.0.0",
5+
"status": "stable",
6+
"effectiveDate": "2026-06-26",
7+
"publicSurfaces": [
8+
"ai/manifest.json",
9+
"ai/content-index.json",
10+
"ai/llms.txt",
11+
"public/llms.txt",
12+
"public/ai/manifest.json",
13+
"public/ai/content-index.json",
14+
"web3://manifest",
15+
"web3://content-index"
16+
],
17+
"compatibilityPolicy": [
18+
"Additive fields may be introduced without changing artifactContract.version.",
19+
"Removing or renaming top-level fields requires a major artifactContract.version change.",
20+
"schemaVersion records the generated content schema date and may change independently."
21+
],
22+
"localMcpPolicy": {
23+
"free": true,
24+
"readOnly": true,
25+
"paymentEnforcement": false,
26+
"chainOperations": false,
27+
"repositoryWrites": false
28+
},
29+
"monetizationPolicy": {
30+
"futurePaidMetadataOnly": true,
31+
"x402EnforcementLive": false,
32+
"preferredFirstPath": "manual sponsorship or GitHub Sponsors-supported access before x402 or Stripe"
33+
}
34+
},
35+
"generatedAt": "2026-06-26T01:12:46.526Z",
436
"repository": {
537
"name": "Get-Started-with-Web3",
638
"owner": "beihaili",
@@ -20197,6 +20229,12 @@
2019720229
"name": "search_web3_content",
2019820230
"title": "Search Web3 Course Content",
2019920231
"description": "Search lesson titles, headings, excerpts, and glossary definitions.",
20232+
"availability": "local-read-only",
20233+
"localMcp": {
20234+
"exposed": true,
20235+
"readOnly": true,
20236+
"free": true
20237+
},
2020020238
"x402": {
2020120239
"enabled": false
2020220240
}
@@ -20205,6 +20243,12 @@
2020520243
"name": "read_web3_lesson",
2020620244
"title": "Read Web3 Lesson",
2020720245
"description": "Read a full lesson by language and lesson identifier.",
20246+
"availability": "local-read-only",
20247+
"localMcp": {
20248+
"exposed": true,
20249+
"readOnly": true,
20250+
"free": true
20251+
},
2020820252
"x402": {
2020920253
"enabled": false
2021020254
}
@@ -20213,6 +20257,12 @@
2021320257
"name": "get_learning_path",
2021420258
"title": "Get Learning Path",
2021520259
"description": "Return role-based learning paths for beginners, builders, researchers, and investors.",
20260+
"availability": "local-read-only",
20261+
"localMcp": {
20262+
"exposed": true,
20263+
"readOnly": true,
20264+
"free": true
20265+
},
2021620266
"x402": {
2021720267
"enabled": false
2021820268
}
@@ -20221,6 +20271,12 @@
2022120271
"name": "lookup_web3_glossary",
2022220272
"title": "Lookup Web3 Glossary",
2022320273
"description": "Search concise glossary entries for Web3 concepts.",
20274+
"availability": "local-read-only",
20275+
"localMcp": {
20276+
"exposed": true,
20277+
"readOnly": true,
20278+
"free": true
20279+
},
2022420280
"x402": {
2022520281
"enabled": false
2022620282
}
@@ -20229,6 +20285,12 @@
2022920285
"name": "compose_web3_context",
2023020286
"title": "Compose Web3 Context",
2023120287
"description": "Build a bounded context pack with citations for a topic.",
20288+
"availability": "local-read-only",
20289+
"localMcp": {
20290+
"exposed": true,
20291+
"readOnly": true,
20292+
"free": true
20293+
},
2023220294
"x402": {
2023320295
"enabled": false
2023420296
}
@@ -20237,6 +20299,12 @@
2023720299
"name": "list_monetizable_tools",
2023820300
"title": "List Monetizable Tools",
2023920301
"description": "List future x402-ready paid tool metadata. Local MCP does not enforce payment.",
20302+
"availability": "local-read-only",
20303+
"localMcp": {
20304+
"exposed": true,
20305+
"readOnly": true,
20306+
"free": true
20307+
},
2024020308
"x402": {
2024120309
"enabled": false
2024220310
}
@@ -20245,6 +20313,12 @@
2024520313
"name": "generate_personalized_web3_plan",
2024620314
"title": "Generate Personalized Web3 Plan",
2024720315
"description": "Future paid remote tool that turns learner goals and background into a tailored Web3 study plan.",
20316+
"availability": "future-hosted-metadata",
20317+
"localMcp": {
20318+
"exposed": false,
20319+
"readOnly": false,
20320+
"free": false
20321+
},
2024820322
"x402": {
2024920323
"enabled": true,
2025020324
"priceUsd": 0.25,
@@ -20256,6 +20330,12 @@
2025620330
"name": "audit_learning_answer",
2025720331
"title": "Audit Learning Answer",
2025820332
"description": "Future paid remote tool that reviews a learner answer against repository lessons with cited corrections.",
20333+
"availability": "future-hosted-metadata",
20334+
"localMcp": {
20335+
"exposed": false,
20336+
"readOnly": false,
20337+
"free": false
20338+
},
2025920339
"x402": {
2026020340
"enabled": true,
2026120341
"priceUsd": 0.1,

‎ai/llms.txt‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,18 @@ This repository exposes bilingual Web3 learning content for AI agents.
44

55
Source: https://github.com/beihaili/Get-Started-with-Web3
66
Homepage: https://bhbtc.xyz/
7-
Generated: 2026-06-25T06:15:17.140Z
7+
Generated: 2026-06-26T01:12:46.526Z
88

99
## Artifacts
10+
- Artifact contract: v1.0.0 (stable)
1011
- Manifest: ai/manifest.json
1112
- Content index: ai/content-index.json
1213

1314
## Local MCP
1415
- Command: npm run mcp:web3
1516
- Transport: stdio
1617
- Mode: read-only
18+
- Policy: free local use, no payment enforcement, no chain operations, no repository writes.
1719
- Client config: replace cwd before use.
1820
```json
1921
{
@@ -31,14 +33,14 @@ Generated: 2026-06-25T06:15:17.140Z
3133
```
3234

3335
## Tools
34-
- search_web3_content: Search lesson titles, headings, excerpts, and glossary definitions. (free)
35-
- read_web3_lesson: Read a full lesson by language and lesson identifier. (free)
36-
- get_learning_path: Return role-based learning paths for beginners, builders, researchers, and investors. (free)
37-
- lookup_web3_glossary: Search concise glossary entries for Web3 concepts. (free)
38-
- compose_web3_context: Build a bounded context pack with citations for a topic. (free)
39-
- list_monetizable_tools: List future x402-ready paid tool metadata. Local MCP does not enforce payment. (free)
40-
- generate_personalized_web3_plan: Future paid remote tool that turns learner goals and background into a tailored Web3 study plan. (future x402 $0.25 on base)
41-
- audit_learning_answer: Future paid remote tool that reviews a learner answer against repository lessons with cited corrections. (future x402 $0.1 on base)
36+
- search_web3_content: Search lesson titles, headings, excerpts, and glossary definitions. (local-read-only; free)
37+
- read_web3_lesson: Read a full lesson by language and lesson identifier. (local-read-only; free)
38+
- get_learning_path: Return role-based learning paths for beginners, builders, researchers, and investors. (local-read-only; free)
39+
- lookup_web3_glossary: Search concise glossary entries for Web3 concepts. (local-read-only; free)
40+
- compose_web3_context: Build a bounded context pack with citations for a topic. (local-read-only; free)
41+
- list_monetizable_tools: List future x402-ready paid tool metadata. Local MCP does not enforce payment. (local-read-only; free)
42+
- generate_personalized_web3_plan: Future paid remote tool that turns learner goals and background into a tailored Web3 study plan. (future-hosted-metadata; future x402 $0.25 on base)
43+
- audit_learning_answer: Future paid remote tool that reviews a learner answer against repository lessons with cited corrections. (future-hosted-metadata; future x402 $0.1 on base)
4244

4345
## Public URLs
4446
- llms.txt: https://bhbtc.xyz/llms.txt

‎ai/manifest.json‎

Lines changed: 81 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,38 @@
11
{
22
"schemaVersion": "2026-05-09",
3-
"generatedAt": "2026-06-25T06:15:17.140Z",
3+
"artifactContract": {
4+
"version": "1.0.0",
5+
"status": "stable",
6+
"effectiveDate": "2026-06-26",
7+
"publicSurfaces": [
8+
"ai/manifest.json",
9+
"ai/content-index.json",
10+
"ai/llms.txt",
11+
"public/llms.txt",
12+
"public/ai/manifest.json",
13+
"public/ai/content-index.json",
14+
"web3://manifest",
15+
"web3://content-index"
16+
],
17+
"compatibilityPolicy": [
18+
"Additive fields may be introduced without changing artifactContract.version.",
19+
"Removing or renaming top-level fields requires a major artifactContract.version change.",
20+
"schemaVersion records the generated content schema date and may change independently."
21+
],
22+
"localMcpPolicy": {
23+
"free": true,
24+
"readOnly": true,
25+
"paymentEnforcement": false,
26+
"chainOperations": false,
27+
"repositoryWrites": false
28+
},
29+
"monetizationPolicy": {
30+
"futurePaidMetadataOnly": true,
31+
"x402EnforcementLive": false,
32+
"preferredFirstPath": "manual sponsorship or GitHub Sponsors-supported access before x402 or Stripe"
33+
}
34+
},
35+
"generatedAt": "2026-06-26T01:12:46.526Z",
436
"repository": {
537
"name": "Get-Started-with-Web3",
638
"owner": "beihaili",
@@ -52,6 +84,12 @@
5284
"name": "search_web3_content",
5385
"title": "Search Web3 Course Content",
5486
"description": "Search lesson titles, headings, excerpts, and glossary definitions.",
87+
"availability": "local-read-only",
88+
"localMcp": {
89+
"exposed": true,
90+
"readOnly": true,
91+
"free": true
92+
},
5593
"x402": {
5694
"enabled": false
5795
}
@@ -60,6 +98,12 @@
6098
"name": "read_web3_lesson",
6199
"title": "Read Web3 Lesson",
62100
"description": "Read a full lesson by language and lesson identifier.",
101+
"availability": "local-read-only",
102+
"localMcp": {
103+
"exposed": true,
104+
"readOnly": true,
105+
"free": true
106+
},
63107
"x402": {
64108
"enabled": false
65109
}
@@ -68,6 +112,12 @@
68112
"name": "get_learning_path",
69113
"title": "Get Learning Path",
70114
"description": "Return role-based learning paths for beginners, builders, researchers, and investors.",
115+
"availability": "local-read-only",
116+
"localMcp": {
117+
"exposed": true,
118+
"readOnly": true,
119+
"free": true
120+
},
71121
"x402": {
72122
"enabled": false
73123
}
@@ -76,6 +126,12 @@
76126
"name": "lookup_web3_glossary",
77127
"title": "Lookup Web3 Glossary",
78128
"description": "Search concise glossary entries for Web3 concepts.",
129+
"availability": "local-read-only",
130+
"localMcp": {
131+
"exposed": true,
132+
"readOnly": true,
133+
"free": true
134+
},
79135
"x402": {
80136
"enabled": false
81137
}
@@ -84,6 +140,12 @@
84140
"name": "compose_web3_context",
85141
"title": "Compose Web3 Context",
86142
"description": "Build a bounded context pack with citations for a topic.",
143+
"availability": "local-read-only",
144+
"localMcp": {
145+
"exposed": true,
146+
"readOnly": true,
147+
"free": true
148+
},
87149
"x402": {
88150
"enabled": false
89151
}
@@ -92,6 +154,12 @@
92154
"name": "list_monetizable_tools",
93155
"title": "List Monetizable Tools",
94156
"description": "List future x402-ready paid tool metadata. Local MCP does not enforce payment.",
157+
"availability": "local-read-only",
158+
"localMcp": {
159+
"exposed": true,
160+
"readOnly": true,
161+
"free": true
162+
},
95163
"x402": {
96164
"enabled": false
97165
}
@@ -100,6 +168,12 @@
100168
"name": "generate_personalized_web3_plan",
101169
"title": "Generate Personalized Web3 Plan",
102170
"description": "Future paid remote tool that turns learner goals and background into a tailored Web3 study plan.",
171+
"availability": "future-hosted-metadata",
172+
"localMcp": {
173+
"exposed": false,
174+
"readOnly": false,
175+
"free": false
176+
},
103177
"x402": {
104178
"enabled": true,
105179
"priceUsd": 0.25,
@@ -111,6 +185,12 @@
111185
"name": "audit_learning_answer",
112186
"title": "Audit Learning Answer",
113187
"description": "Future paid remote tool that reviews a learner answer against repository lessons with cited corrections.",
188+
"availability": "future-hosted-metadata",
189+
"localMcp": {
190+
"exposed": false,
191+
"readOnly": false,
192+
"free": false
193+
},
114194
"x402": {
115195
"enabled": true,
116196
"priceUsd": 0.1,

0 commit comments

Comments
 (0)