├── demo
├── .gitkeep
├── snake_game_v2_complete.py
├── js
│ ├── vector3.js
│ ├── camera.js
│ ├── matrix4.js
│ ├── car.js
│ ├── track.js
│ ├── utils.js
│ ├── game.js
│ ├── renderer.js
│ ├── physics.js
│ ├── sound.js
│ └── particles.js
├── index.html
├── style.css
├── styles.css
├── catch_game.html
├── racing_game.html
├── script.js
├── gobang_snake.html
└── game.js
├── requirements.txt
├── articles
├── v2文章.md
└── v1文章.md
├── README.md
├── README_en.md
├── .gitignore
└── v1_basic_agent.py
/demo/.gitkeep:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
/requirements.txt:
--------------------------------------------------------------------------------
1 | pygame==2.5.2
2 | numpy==1.24.3
--------------------------------------------------------------------------------
/demo/snake_game_v2_complete.py:
--------------------------------------------------------------------------------
1 | #!/usr/bin/env python3
2 | # -*- coding: utf-8 -*-
3 | """
4 | 超级贪吃蛇游戏 v2.0 - 完整版
5 | =====================================
6 |
7 | 这是一个功能丰富的贪吃蛇游戏，包含以下特性：
8 |
9 | 🎮 游戏模式:
10 | • 经典模式 - 传统贪吃蛇玩法
11 | • AI对战模式 - 与智能AI对战
12 | • 生存模式 - 带障碍物的挑战模式
13 | • 时间挑战模式 - 限时达成目标
14 | • 无尽模式 - 持续增加的难度
15 | • 多人对战模式 - 本地双人游戏
16 | • 关卡编辑器 - 创建自定义关卡
17 |
18 | 🚀 高级功能:
19 | • A*寻路AI算法
20 | • 游戏进度保存/读取 (F5/F9)
21 | • 成就系统
22 | • 粒子特效
23 | • 音效系统
24 | • 传送门机制
25 | • 地雷陷阱
26 | • 多种道具系统
27 |
28 | 🎯 道具类型:
29 | • 速度提升 - 移动速度加快
30 | • 双倍积分 - 得分翻倍
31 | • 护盾 - 免疫一次伤害
32 | • 幽灵模式 - 穿墙能力
33 | • 传送 - 瞬移到安全位置
34 | • 炸弹 - 清除周围障碍物
35 | • 时间冻结 - 暂停时间计时
36 |
37 | 🎨 视觉效果:
38 | • 动态粒子系统
39 | • 传送门动画
40 | • 护盾光环效果
41 | • 渐变蛇身颜色
42 | • 脉冲道具动画
43 |
44 | 📊 游戏统计:
45 | • 详细的游戏数据统计
46 | • 成就追踪
47 | • 关卡解锁系统
48 | • 高分记录
49 |
50 | 控制方式:
51 | ---------
52 | 玩家1:
53 | 方向键 - 移动
54 | B - 使用炸弹
55 | T - 使用传送
56 | 空格 - 暂停/继续
57 | F5 - 快速保存
58 | F9 - 快速加载
59 | ESC - 退出游戏
60 |
61 | 玩家2 (多人模式):
62 | WASD - 移动
63 |
64 | 关卡编辑器:
65 | ---------
66 | 1-5 - 选择工具
67 | 左键 - 放置元素
68 | 右键 - 移除元素
69 | S - 保存关卡
70 | C - 清空关卡
71 | G - 切换网格吸附
72 | H - 显示/隐藏帮助
73 | ESC - 退出编辑器
74 |
75 | 作者: AI Assistant
76 | 版本: 2.0
77 | """
78 |
79 | # 合并所有代码到一个文件
80 | exec(open("snake_game_v2.py").read())
81 | exec(open("snake_game_v2_main.py").read())
82 |
83 | if __name__ == "__main__":
84 | main()
85 |
--------------------------------------------------------------------------------
/articles/v2文章.md:
--------------------------------------------------------------------------------
1 | # mini Kode v2：让模型自我约束的 Todo 工具
2 |
3 | v1 版本的 mini Kode 已经证明：只要把大模型嵌入一个简洁的工具循环，它就能像“代码工人”一样在本地仓库里读写文件、执行命令。但我们也遇到一个老问题——**模型是否真的在有计划地推进任务？**
4 |
5 | 顺便推荐一下我们维护的 Kode 项目：这是面向生产的开源版 Claude Code，收录了 Bash 扩展、WebSearch / WebFetch、Docker 适配等高级能力，适合直接落地企业级场景。若你在寻找更多资料，也可以参考我们先前整理的一系列开源实现与逆向分析，它们共同构成了如今 mini Kode 的“孵化器”。
6 |
7 | 在 v2 中，我们引入了一个看似朴素、却改变工作流体验的核心能力：**Todo 工具链**。它把“规划—执行—复盘”的节奏落在了代码级别，迫使模型对复杂任务进行显式拆解，从而让用户和模型都能清楚地看到每一步发生了什么。
8 |
9 | ## 1. 具体做了什么？
10 |
11 | - **新增 TodoWrite 工具与 TodoManager**：在工具列表中加入 `TodoWrite`，由 `TodoManager` 维护一个至多 20 条的任务列表，约束只允许一个条目处于 `in_progress`，并在每次更新时返回彩色状态视图与统计数据。
12 | - **消息循环挂钩待办状态**：在每轮模型输出后，如果出现对 Todo 的调用，就把更新结果作为工具反馈写回对话历史，让模型看到自己刚刚操作的“计划板”，形成自监督闭环。
13 | - **系统提醒机制**：在会话伊始植入 system reminder，如果连续 10 轮交互未触发 Todo，再次注入温和提醒，让模型持续感知“规划要求”；每次真正更新 Todo 后则重置计数器。
14 | - **严格输入校验**：对 Todo 输入的 `id`、`status`、`activeForm` 等字段进行检查，防止模型写入空任务、重复条目或异常状态，引导它遵循清晰的规范。
15 |
16 | ## 2. 背后的思想
17 |
18 | > **模型依旧是核心，但要用规则把它“拴”在结构化工作流里。**
19 |
20 | 1. **结构化约束代替自由生成**：单纯的文本指令很容易让模型忘记计划，Todo 工具则把“计划”实体化为数据结构，模型只有维护好它才能继续执行。
21 | 2. **显式反馈增强自我监督**：每次 Todo 更新都会立即显示当前状态，模型能在下一轮读到这段文本，相当于用环境反馈提醒它“你现在在做哪一步”。
22 | 3. **系统提示形成软约束**：提醒块不是条件语句，而是上下文资料；它们用最小侵入的方式告诉模型“别忘记 Todo”，既保留灵活性，又能降低跑偏概率。
23 |
24 | ## 3. 能应用到哪些场景？
25 |
26 | - **多步骤代码任务**：例如“写接口 → 补测试 → 更新文档”，模型必须先把步骤写进 Todo，然后逐项勾选，用户可以随时检查进度。
27 | - **长周期对话**：在需要几十轮推演的需求中，system reminder 会周期性提醒模型遵守规划流程，避免它在自由文本里迷失。
28 | - **团队协同与审计**：把 Todo 输出存档，就能追踪模型在每次会话里的计划与执行痕迹，为回顾和复盘提供依据。
29 |
30 | v1 的意义在于验证“模型 as agent”这一底层设计；v2 则进一步证明：**只要给模型配备合适的结构化工具，它不仅能执行，更能规划、记忆和自我纠错**。后续我们还会继续叠加 Task 子代理与更丰富的 system reminder 组合，并把 Kode 里的成熟特性不断反馈到 mini Kode，让它逐步靠近真实产品级 Agent 的形态。
31 |
--------------------------------------------------------------------------------
/demo/js/vector3.js:
--------------------------------------------------------------------------------
1 | class Vector3 {
2 | constructor(x = 0, y = 0, z = 0) {
3 | this.x = x;
4 | this.y = y;
5 | this.z = z;
6 | }
7 |
8 | clone() {
9 | return new Vector3(this.x, this.y, this.z);
10 | }
11 |
12 | add(v) {
13 | return new Vector3(this.x + v.x, this.y + v.y, this.z + v.z);
14 | }
15 |
16 | subtract(v) {
17 | return new Vector3(this.x - v.x, this.y - v.y, this.z - v.z);
18 | }
19 |
20 | multiply(scalar) {
21 | return new Vector3(this.x * scalar, this.y * scalar, this.z * scalar);
22 | }
23 |
24 | divide(scalar) {
25 | return new Vector3(this.x / scalar, this.y / scalar, this.z / scalar);
26 | }
27 |
28 | dot(v) {
29 | return this.x * v.x + this.y * v.y + this.z * v.z;
30 | }
31 |
32 | cross(v) {
33 | return new Vector3(
34 | this.y * v.z - this.z * v.y,
35 | this.z * v.x - this.x * v.z,
36 | this.x * v.y - this.y * v.x
37 | );
38 | }
39 |
40 | length() {
41 | return Math.sqrt(this.x * this.x + this.y * this.y + this.z * this.z);
42 | }
43 |
44 | normalize() {
45 | const len = this.length();
46 | if (len === 0) return new Vector3(0, 0, 0);
47 | return this.divide(len);
48 | }
49 |
50 | distance(v) {
51 | return this.subtract(v).length();
52 | }
53 |
54 | rotateY(angle) {
55 | const cos = Math.cos(angle);
56 | const sin = Math.sin(angle);
57 | return new Vector3(
58 | this.x * cos - this.z * sin,
59 | this.y,
60 | this.x * sin + this.z * cos
61 | );
62 | }
63 |
64 | toString() {
65 | return `(${this.x.toFixed(2)}, ${this.y.toFixed(2)}, ${this.z.toFixed(2)})`;
66 | }
67 | }
--------------------------------------------------------------------------------
/demo/js/camera.js:
--------------------------------------------------------------------------------
1 | class Camera {
2 | constructor(fov = 60, aspect = 1, near = 0.1, far = 1000) {
3 | this.position = new Vector3(0, 5, -10);
4 | this.target = new Vector3(0, 0, 0);
5 | this.up = new Vector3(0, 1, 0);
6 |
7 | this.fov = fov * Math.PI / 180;
8 | this.aspect = aspect;
9 | this.near = near;
10 | this.far = far;
11 |
12 | this.viewMatrix = new Matrix4();
13 | this.projectionMatrix = new Matrix4();
14 | this.viewProjectionMatrix = new Matrix4();
15 |
16 | this.followDistance = 15;
17 | this.followHeight = 8;
18 | this.smoothness = 0.1;
19 | }
20 |
21 | setAspectRatio(aspect) {
22 | this.aspect = aspect;
23 | this.updateProjectionMatrix();
24 | }
25 |
26 | updateProjectionMatrix() {
27 | this.projectionMatrix.identity().perspective(this.fov, this.aspect, this.near, this.far);
28 | }
29 |
30 | updateViewMatrix() {
31 | this.viewMatrix.identity().lookAt(this.position, this.target, this.up);
32 | }
33 |
34 | updateMatrices() {
35 | this.updateViewMatrix();
36 | this.updateProjectionMatrix();
37 | this.viewProjectionMatrix.copy(this.projectionMatrix).multiply(this.viewMatrix);
38 | }
39 |
40 | followCar(car) {
41 | const idealPosition = car.position
42 | .add(new Vector3(0, this.followHeight, 0))
43 | .subtract(car.forward.multiply(this.followDistance));
44 |
45 | this.position = this.position.add(idealPosition.subtract(this.position).multiply(this.smoothness));
46 | this.target = car.position.add(new Vector3(0, 2, 0));
47 |
48 | this.updateMatrices();
49 | }
50 |
51 | worldToScreen(worldPos) {
52 | const clipPos = this.viewProjectionMatrix.transformVector(worldPos);
53 |
54 | return {
55 | x: (clipPos.x + 1) * 0.5,
56 | y: (1 - clipPos.y) * 0.5,
57 | z: clipPos.z
58 | };
59 | }
60 | }
--------------------------------------------------------------------------------
/demo/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 | 3D赛车游戏
7 |
67 |
68 |
69 |
70 |
3D赛车游戏
71 |
72 |
73 |
74 |
75 |
速度: 0 km/h
76 |
圈数: 0/3
77 |
时间: 0s
78 |
81 |
控制说明
82 |
↑ - 加速 | ↓ - 刹车 | ← → - 转向
83 |
空格 - 手刹 | R - 重置位置
84 |
5 | Fellow us on X: https://x.com/baicai003
6 |
7 | 
8 | 
9 |
10 | 
11 |
12 | 本仓库展示了一个逐步迭代的「迷你 Kode」实现。我们用最少的代码复刻官方工作流的关键体验，分为两个主要版本：
13 |
14 | - **v1 基础版**：聚焦「模型即代理（Model as Agent）」的核心循环，让大模型在一个最小可用的 CLI 中读取、编辑、写入文件并执行命令。
15 | - **v2 待办版**：在 v1 的基础上，引入结构化计划工具（Todo）、系统提醒等机制，使模型具备显式规划和自我监督能力。
16 |
17 | 以下内容将详细介绍两个版本的运转原理，以及它们之间的思想差异。
18 |
19 | ---
20 |
21 | ## v1：Model as Agent 的最小实现
22 |
23 | v1 版本的目标是验证“代码只负责提供工具，大模型才是唯一的行为主体”这一理念。整个 CLI 只有约 400 行 Python 代码，却包含了 Agent 最关键的要素：
24 |
25 | ### 1. 系统角色设定
26 | - 通过 `SYSTEM` 字符串明确约束模型：以仓库为工作区、优先用工具行动、结束时要总结。
27 | - 这些规则让模型在长对话里始终记得“该做事”而不是“闲聊”。
28 |
29 | ### 2. 统一的工具调度
30 | - 预置了四个核心工具：`bash`、`read_file`、`write_file`、`edit_text`。
31 | - 调度逻辑会根据模型的 `tool_use` 块调用对应的执行函数，输出结果再以 `tool_result` 写回对话。
32 | - 所有工具都带有安全检查（路径约束、危险命令禁用、输出裁剪），确保运行可控。
33 |
34 | ### 3. 控制台体验
35 | - `Spinner` 线程在模型推理时显示等待动画。
36 | - `pretty_tool_line` 和 `pretty_sub_line` 负责把每次工具调用的标题与输出排版成易读的格式。
37 | - 与模型的对话历史被完整保留在 `messages` 中，确保上下文一致性。
38 |
39 | ### 4. 主循环行为
40 | - CLI 启动后提示工作目录，用户输入即时追加到 `history`。
41 | - 每轮调用 `client.messages.create`，若模型请求使用工具，则递归处理直到返回最终文本。
42 | - 异常处理通过 `log_error_debug` 记录，避免 CLI 直接崩溃。
43 |
44 | > **核心理念：** 只要提供一个稳定的“工具壳”，模型就能主动完成绝大多数编码任务。v1 证明了 Kode 成功的秘诀不在各种节点雕花流转，而在于让模型保持连续上下文 + 拥有持续调用工具的能力。
45 |
46 | ---
47 |
48 | ## v2：结构化规划与系统提醒
49 |
50 | v2 在 v1 的基础上，重点解决“模型如何保持有序规划”这个问题。我们新增了 Todo 工具链与系统提醒机制，让模型始终处于结构化、可追踪的工作流中。
51 |
52 | ### 1. Todo 工具链
53 | - **`TodoManager`**：维护最多 20 条待办，强制唯一的 `in_progress` 条目，并对输入做严格校验（ID、状态、描述、表单名称）。
54 | - **`TodoWrite` 工具**：模型可以调用它来创建、更新、完成待办，CLI 会即时渲染彩色状态并输出统计结果。
55 | - **状态可视化**：
56 | - `pending` → 柔和灰色
57 | - `in_progress` → 高亮蓝色
58 | - `completed` → 绿色并带删除线
59 |
60 | 通过 Todo 面板，模型和用户都能清楚看到当前计划、正在进行的步骤以及已完成情况。
61 |
62 | ### 2. System Reminder（系统提醒）
63 | - **初始提醒**：会话开始前，将「请使用 Todo 工具管理多步骤任务」作为特殊上下文块注入。
64 | - **周期提醒**：如果连续 10 轮对话没有 Todo 更新，会再注入一次提醒，温和提示模型恢复规划。
65 | - **自动重置**：每当 Todo 有更新，计数器归零，避免重复“催促”。
66 |
67 | 这一机制确保模型不会在长对话里忘记使用 Todo，也让用户免于手动监督。
68 |
69 | ### 3. 交互流程改动
70 | - 输入阶段：将用户消息与待发送的提醒块合并为同一组 content，维护对话一致性。
71 | - 输出阶段：Todo 工具的结果即时打印，并写入历史，让模型在下一轮能够“看到”自己刚刚更新的计划。
72 | - 文案统一：所有提示与汇报改为英文，保持更适合海外产品的风格（代码中不再包含中文）。
73 |
74 | ### 4. 设计收益
75 | - **结构化约束**：模型必须先规划再执行，避免“想到哪写到哪”。
76 | - **自我监督**：Todo 视图是模型的外部记忆，持续提醒它当前所处的步骤。
77 | - **可追溯**：整个会话的待办记录可用于回顾与审计。
78 |
79 | > **扩展链接**：如果想体验生产级的 Claude Code 工作流，推荐试试我们维护的开源项目 [Kode](https://github.com/shareAI-lab/Kode)。它在这个迷你仓库的基础上加入了 Bash 扩展、WebSearch/WebFetch、Docker 支持、IDE 插件等高级功能。
80 |
81 | ---
82 |
83 | ## 总结
84 |
85 | - **v1 思想**：构建最小工具循环，证明“模型即代理”的可行性。
86 | - **v2 思想**：在最小循环上加固结构化规划与系统提醒，让模型具备可视化的计划能力和自我约束力。
87 |
88 | 接下来，我们还计划在 mini Kode 中逐步引入 Task 子代理、更多类型的提醒矩阵等能力，并把 Kode 项目中沉淀的实践回流到这个教学仓库，帮助更多开发者快速理解并构建自己的智能代理系统。
89 |
--------------------------------------------------------------------------------
/demo/style.css:
--------------------------------------------------------------------------------
1 | * {
2 | margin: 0;
3 | padding: 0;
4 | box-sizing: border-box;
5 | }
6 |
7 | body {
8 | font-family: 'Arial', sans-serif;
9 | background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
10 | min-height: 100vh;
11 | display: flex;
12 | justify-content: center;
13 | align-items: center;
14 | color: white;
15 | }
16 |
17 | .container {
18 | text-align: center;
19 | padding: 20px;
20 | background: rgba(255, 255, 255, 0.1);
21 | border-radius: 20px;
22 | backdrop-filter: blur(10px);
23 | box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
24 | border: 1px solid rgba(255, 255, 255, 0.2);
25 | }
26 |
27 | h1 {
28 | margin-bottom: 20px;
29 | font-size: 2.5em;
30 | text-shadow: 2px 2px 4px rgba(0, 0, 0, 0.5);
31 | background: linear-gradient(45deg, #4facfe, #00f2fe);
32 | -webkit-background-clip: text;
33 | -webkit-text-fill-color: transparent;
34 | background-clip: text;
35 | }
36 |
37 | .controls {
38 | margin-bottom: 20px;
39 | display: flex;
40 | justify-content: center;
41 | align-items: center;
42 | gap: 15px;
43 | flex-wrap: wrap;
44 | }
45 |
46 | .controls label {
47 | font-weight: bold;
48 | font-size: 14px;
49 | }
50 |
51 | .controls input[type="range"] {
52 | width: 100px;
53 | height: 5px;
54 | border-radius: 5px;
55 | background: rgba(255, 255, 255, 0.3);
56 | outline: none;
57 | -webkit-appearance: none;
58 | }
59 |
60 | .controls input[type="range"]::-webkit-slider-thumb {
61 | -webkit-appearance: none;
62 | appearance: none;
63 | width: 20px;
64 | height: 20px;
65 | border-radius: 50%;
66 | background: linear-gradient(45deg, #4facfe, #00f2fe);
67 | cursor: pointer;
68 | box-shadow: 0 2px 6px rgba(0, 0, 0, 0.3);
69 | }
70 |
71 | .controls input[type="range"]::-moz-range-thumb {
72 | width: 20px;
73 | height: 20px;
74 | border-radius: 50%;
75 | background: linear-gradient(45deg, #4facfe, #00f2fe);
76 | cursor: pointer;
77 | border: none;
78 | box-shadow: 0 2px 6px rgba(0, 0, 0, 0.3);
79 | }
80 |
81 | .controls span {
82 | font-weight: bold;
83 | color: #00f2fe;
84 | min-width: 30px;
85 | }
86 |
87 | #resetBtn {
88 | padding: 8px 16px;
89 | background: linear-gradient(45deg, #ff6b6b, #ee5a24);
90 | color: white;
91 | border: none;
92 | border-radius: 20px;
93 | cursor: pointer;
94 | font-weight: bold;
95 | transition: all 0.3s ease;
96 | box-shadow: 0 4px 15px rgba(238, 90, 36, 0.3);
97 | }
98 |
99 | #resetBtn:hover {
100 | transform: translateY(-2px);
101 | box-shadow: 0 6px 20px rgba(238, 90, 36, 0.4);
102 | }
103 |
104 | #waterCanvas {
105 | border: 3px solid rgba(255, 255, 255, 0.3);
106 | border-radius: 15px;
107 | background: linear-gradient(135deg, #1e3c72, #2a5298);
108 | box-shadow: 0 10px 30px rgba(0, 0, 0, 0.3);
109 | cursor: crosshair;
110 | transition: all 0.3s ease;
111 | }
112 |
113 | #waterCanvas:hover {
114 | box-shadow: 0 15px 40px rgba(0, 0, 0, 0.4);
115 | transform: translateY(-2px);
116 | }
117 |
118 | .info {
119 | margin-top: 15px;
120 | font-size: 14px;
121 | color: rgba(255, 255, 255, 0.8);
122 | font-style: italic;
123 | }
124 |
125 | @media (max-width: 768px) {
126 | .container {
127 | padding: 15px;
128 | margin: 10px;
129 | }
130 |
131 | h1 {
132 | font-size: 2em;
133 | }
134 |
135 | #waterCanvas {
136 | width: 100%;
137 | max-width: 600px;
138 | height: auto;
139 | }
140 |
141 | .controls {
142 | gap: 10px;
143 | }
144 |
145 | .controls input[type="range"] {
146 | width: 80px;
147 | }
148 | }
149 |
150 | @media (max-width: 480px) {
151 | h1 {
152 | font-size: 1.5em;
153 | }
154 |
155 | .controls {
156 | flex-direction: column;
157 | gap: 8px;
158 | }
159 |
160 | .controls label {
161 | font-size: 12px;
162 | }
163 | }
--------------------------------------------------------------------------------
/demo/js/matrix4.js:
--------------------------------------------------------------------------------
1 | class Matrix4 {
2 | constructor() {
3 | this.elements = [
4 | 1, 0, 0, 0,
5 | 0, 1, 0, 0,
6 | 0, 0, 1, 0,
7 | 0, 0, 0, 1
8 | ];
9 | }
10 |
11 | identity() {
12 | this.elements = [
13 | 1, 0, 0, 0,
14 | 0, 1, 0, 0,
15 | 0, 0, 1, 0,
16 | 0, 0, 0, 1
17 | ];
18 | return this;
19 | }
20 |
21 | copy(m) {
22 | this.elements = m.elements.slice();
23 | return this;
24 | }
25 |
26 | multiply(m) {
27 | const a = this.elements;
28 | const b = m.elements;
29 | const result = new Array(16);
30 |
31 | for (let i = 0; i < 4; i++) {
32 | for (let j = 0; j < 4; j++) {
33 | result[i * 4 + j] = 0;
34 | for (let k = 0; k < 4; k++) {
35 | result[i * 4 + j] += a[i * 4 + k] * b[k * 4 + j];
36 | }
37 | }
38 | }
39 |
40 | this.elements = result;
41 | return this;
42 | }
43 |
44 | translate(x, y, z) {
45 | const translation = new Matrix4();
46 | translation.elements[12] = x;
47 | translation.elements[13] = y;
48 | translation.elements[14] = z;
49 | return this.multiply(translation);
50 | }
51 |
52 | rotateX(angle) {
53 | const cos = Math.cos(angle);
54 | const sin = Math.sin(angle);
55 | const rotation = new Matrix4();
56 | rotation.elements[5] = cos;
57 | rotation.elements[6] = -sin;
58 | rotation.elements[9] = sin;
59 | rotation.elements[10] = cos;
60 | return this.multiply(rotation);
61 | }
62 |
63 | rotateY(angle) {
64 | const cos = Math.cos(angle);
65 | const sin = Math.sin(angle);
66 | const rotation = new Matrix4();
67 | rotation.elements[0] = cos;
68 | rotation.elements[2] = sin;
69 | rotation.elements[8] = -sin;
70 | rotation.elements[10] = cos;
71 | return this.multiply(rotation);
72 | }
73 |
74 | rotateZ(angle) {
75 | const cos = Math.cos(angle);
76 | const sin = Math.sin(angle);
77 | const rotation = new Matrix4();
78 | rotation.elements[0] = cos;
79 | rotation.elements[1] = -sin;
80 | rotation.elements[4] = sin;
81 | rotation.elements[5] = cos;
82 | return this.multiply(rotation);
83 | }
84 |
85 | scale(x, y, z) {
86 | const scaling = new Matrix4();
87 | scaling.elements[0] = x;
88 | scaling.elements[5] = y;
89 | scaling.elements[10] = z;
90 | return this.multiply(scaling);
91 | }
92 |
93 | perspective(fov, aspect, near, far) {
94 | const f = 1.0 / Math.tan(fov / 2);
95 | const rangeInv = 1 / (near - far);
96 |
97 | this.elements = [
98 | f / aspect, 0, 0, 0,
99 | 0, f, 0, 0,
100 | 0, 0, (near + far) * rangeInv, -1,
101 | 0, 0, near * far * rangeInv * 2, 0
102 | ];
103 | return this;
104 | }
105 |
106 | lookAt(eye, center, up) {
107 | const f = center.subtract(eye).normalize();
108 | const s = f.cross(up).normalize();
109 | const u = s.cross(f);
110 |
111 | this.elements = [
112 | s.x, u.x, -f.x, 0,
113 | s.y, u.y, -f.y, 0,
114 | s.z, u.z, -f.z, 0,
115 | -s.dot(eye), -u.dot(eye), f.dot(eye), 1
116 | ];
117 | return this;
118 | }
119 |
120 | transformVector(v) {
121 | const x = v.x * this.elements[0] + v.y * this.elements[4] + v.z * this.elements[8] + this.elements[12];
122 | const y = v.x * this.elements[1] + v.y * this.elements[5] + v.z * this.elements[9] + this.elements[13];
123 | const z = v.x * this.elements[2] + v.y * this.elements[6] + v.z * this.elements[10] + this.elements[14];
124 | const w = v.x * this.elements[3] + v.y * this.elements[7] + v.z * this.elements[11] + this.elements[15];
125 |
126 | return new Vector3(x / w, y / w, z / w);
127 | }
128 | }
--------------------------------------------------------------------------------
/demo/js/car.js:
--------------------------------------------------------------------------------
1 | class Car {
2 | constructor() {
3 | this.position = new Vector3(0, 0.5, 0);
4 | this.velocity = new Vector3(0, 0, 0);
5 | this.acceleration = new Vector3(0, 0, 0);
6 |
7 | this.forward = new Vector3(0, 0, 1);
8 | this.right = new Vector3(1, 0, 0);
9 | this.up = new Vector3(0, 1, 0);
10 |
11 | this.speed = 0;
12 | this.maxSpeed = 200;
13 | this.accelerationForce = 100;
14 | this.brakeForce = 150;
15 | this.friction = 0.95;
16 | this.turnSpeed = 0.03;
17 |
18 | this.steering = 0;
19 | this.throttle = 0;
20 | this.brake = 0;
21 |
22 | this.width = 2;
23 | this.height = 1;
24 | this.length = 4;
25 |
26 | this.wheelBase = 2.5;
27 | this.trackWidth = 1.8;
28 |
29 | this.onGround = true;
30 | this.mass = 1000;
31 |
32 | this.wheelRotation = 0;
33 | this.bodyRoll = 0;
34 | this.bodyPitch = 0;
35 |
36 | this.color = '#' + Math.floor(Math.random()*16777215).toString(16).padStart(6, '0');
37 | }
38 |
39 | update(deltaTime, input) {
40 | this.handleInput(input);
41 | this.updatePhysics(deltaTime);
42 | this.updateVisuals(deltaTime);
43 | }
44 |
45 | handleInput(input) {
46 | this.throttle = 0;
47 | this.brake = 0;
48 | this.steering = 0;
49 |
50 | if (input.forward) this.throttle = 1;
51 | if (input.backward) this.brake = 1;
52 | if (input.left) this.steering = -1;
53 | if (input.right) this.steering = 1;
54 | if (input.handbrake) this.brake = 1.5;
55 |
56 | if (input.reset) {
57 | this.reset();
58 | }
59 | }
60 |
61 | updatePhysics(deltaTime) {
62 | const dt = deltaTime;
63 |
64 | if (this.speed > 0.1) {
65 | const turnAmount = this.steering * this.turnSpeed * (this.speed / this.maxSpeed);
66 | this.forward = this.forward.rotateY(turnAmount);
67 | this.right = this.forward.cross(this.up);
68 | }
69 |
70 | const engineForce = this.throttle * this.accelerationForce;
71 | const brakeForce = this.brake * this.brakeForce;
72 |
73 | const dragForce = this.speed * this.speed * 0.001;
74 | const rollingResistance = this.speed * 0.5;
75 |
76 | const totalForce = engineForce - brakeForce - dragForce - rollingResistance;
77 |
78 | this.speed += totalForce * dt;
79 | this.speed = Math.max(0, Math.min(this.speed, this.maxSpeed));
80 |
81 | if (this.speed < 0.1 && this.brake > 0) {
82 | this.speed = Math.max(this.speed - this.brakeForce * dt * 0.5, -this.maxSpeed * 0.3);
83 | }
84 |
85 | this.velocity = this.forward.multiply(this.speed);
86 |
87 | this.position = this.position.add(this.velocity.multiply(dt));
88 |
89 | this.wheelRotation += this.speed * dt * 0.1;
90 |
91 | this.bodyRoll = this.steering * Math.min(this.speed / this.maxSpeed, 1) * 0.2;
92 | this.bodyPitch = (this.throttle - this.brake * 0.5) * Math.min(this.speed / this.maxSpeed, 1) * 0.1;
93 | }
94 |
95 | updateVisuals(deltaTime) {
96 | // Update visual effects based on physics
97 | }
98 |
99 | reset() {
100 | this.position = new Vector3(0, 0.5, 0);
101 | this.velocity = new Vector3(0, 0, 0);
102 | this.speed = 0;
103 | this.forward = new Vector3(0, 0, 1);
104 | this.right = new Vector3(1, 0, 0);
105 | this.steering = 0;
106 | this.throttle = 0;
107 | this.brake = 0;
108 | this.wheelRotation = 0;
109 | this.bodyRoll = 0;
110 | this.bodyPitch = 0;
111 | }
112 |
113 | getCorners() {
114 | const halfWidth = this.width / 2;
115 | const halfLength = this.length / 2;
116 |
117 | const corners = [
118 | new Vector3(-halfWidth, 0, -halfLength), // Front-left
119 | new Vector3(halfWidth, 0, -halfLength), // Front-right
120 | new Vector3(halfWidth, 0, halfLength), // Rear-right
121 | new Vector3(-halfWidth, 0, halfLength) // Rear-left
122 | ];
123 |
124 | return corners.map(corner => {
125 | const rotated = new Vector3(
126 | corner.x * this.right.x + corner.z * this.forward.x,
127 | corner.y + this.bodyPitch * corner.z - this.bodyRoll * corner.x,
128 | corner.x * this.right.z + corner.z * this.forward.z
129 | );
130 | return rotated.add(this.position);
131 | });
132 | }
133 |
134 | getSpeedKMH() {
135 | return this.speed * 3.6;
136 | }
137 | }
--------------------------------------------------------------------------------
/README_en.md:
--------------------------------------------------------------------------------
1 | # mini Kode Agent
2 |
3 | This repository showcases a step-by-step recreation of a “mini Kode” workflow. With a few hundred lines of Python we rebuild the essential loops behind Anthropic’s engineering assistant and release them in two major stages:
4 |
5 | - **v1 (baseline)** – demonstrates the core *model-as-agent* loop: the LLM is the only decision maker, the CLI just exposes tools for reading, editing, writing files, and running shell commands.
6 | - **v2 (todos)** – layers structured planning on top of v1 with a shared todo board and system reminders so the model stays disciplined during multi-step tasks.
7 |
8 | Below is a detailed walkthrough of how each version operates and what changed between them.
9 |
10 | ---
11 |
12 | ## v1: Minimal “Model as Agent” Loop
13 |
14 | The first version proves a simple principle: **code supplies tools, the model drives the work**. About 400 lines of Python cover the following pillars:
15 |
16 | ### 1. System prompt guardrails
17 | - The `SYSTEM` string reminds the model that it lives inside the repository, must act through tools, and should summarize when finished.
18 | - This keeps multi-turn conversations action oriented instead of drifting into idle chat.
19 |
20 | ### 2. Unified tool dispatch
21 | - The CLI exposes four tools: `bash`, `read_file`, `write_file`, and `edit_text`.
22 | - When the model outputs a `tool_use` block, the dispatcher runs the corresponding helper and returns a `tool_result` block with truncated, colorized output.
23 | - Safety checks gate the tools (path validation, banned commands, output clamping) to prevent runaway actions.
24 |
25 | ### 3. Terminal experience
26 | - A background `Spinner` thread indicates model latency.
27 | - `pretty_tool_line` and `pretty_sub_line` format every tool call in a readable, ANSI-colored layout.
28 | - The full conversation is stored in `messages`, preserving context across tool invocations.
29 |
30 | ### 4. Main event loop
31 | - The CLI prints the current workspace, accepts user input, and appends it to history.
32 | - Each turn calls `client.messages.create`; if the model wants tools, the loop recursively executes them until plain text is returned.
33 | - Errors are caught by `log_error_debug` so the session doesn’t crash.
34 |
35 | > **Key insight:** a stable tool shell plus a focused system prompt is enough to let the model behave like a real coding agent. UI polish is optional; tool access is everything.
36 |
37 | ---
38 |
39 | ## v2: Structured Planning and System Reminders
40 |
41 | Version 2 answers a natural question: *how do we keep the model organized over longer tasks?* The upgrade introduces a todo board, a reminder mechanism, and English-only copy to keep the workflow predictable.
42 |
43 | ### 1. Todo toolchain
44 | - **`TodoManager`** maintains up to 20 entries, guarantees at most one `in_progress` item, and validates IDs, statuses, and descriptions.
45 | - **`TodoWrite`** becomes a first-class tool. The model calls it to create/update/complete todos; the CLI immediately renders colored status lines plus summary stats.
46 | - **Status colors** use a consistent palette: grey for pending, blue for in progress, green with strikethrough for completed.
47 |
48 | ### 2. System reminders
49 | - **Initial reminder:** before the first user message, a system block instructs the model to manage multi-step work through the todo board.
50 | - **10-turn reminder:** if ten consecutive turns pass without a todo update, another reminder block is injected to nudge the model back to structured planning.
51 | - **Auto reset:** every todo update resets the counter so reminders only trigger when discipline lapses.
52 |
53 | ### 3. Interaction changes
54 | - On input, user text and any pending reminders are bundled into a single content list so the model sees consistent context.
55 | - On output, todo results are printed immediately and appended to history, giving the model a short-term memory of its own plan.
56 | - All messages, summaries, and errors are now in English to match the neutral CLI aesthetic.
57 |
58 | ### 4. Benefits
59 | - **Structured guardrails:** the model has to plan before acting, reducing “winging it” behavior.
60 | - **Self-supervision:** the todo board is an external memory surface that keeps current priorities visible.
61 | - **Auditability:** the session transcript contains every todo change, which makes reviews and debugging easier.
62 |
63 | > **Looking for a production-ready toolkit?** Check out [Kode](https://github.com/shareAI-lab/Kode), the open-source Claude Code implementation we maintain. It adds Windows Bash support, WebSearch/WebFetch, Docker adapters, and IDE plugins on top of the ideas explored here.
64 |
65 | ---
66 |
67 | ## Summary
68 |
69 | - **v1 philosophy:** prove the minimal model-as-agent loop—tools are thin wrappers, the LLM carries the project.
70 | - **v2 philosophy:** enforce explicit planning via todos and system reminders so the workflow stays organized and transparent.
71 |
72 | Future iterations will experiment with sub-agent tasks, richer reminder matrices, and will keep backporting mature features from Kode into this learning-friendly codebase. Contributions and experiments are welcome!
73 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | # Byte-compiled / optimized / DLL files
2 | __pycache__/
3 | *.py[codz]
4 | *$py.class
5 |
6 | # C extensions
7 | *.so
8 |
9 | # Distribution / packaging
10 | .Python
11 | build/
12 | develop-eggs/
13 | dist/
14 | downloads/
15 | eggs/
16 | .eggs/
17 | lib/
18 | lib64/
19 | parts/
20 | sdist/
21 | var/
22 | wheels/
23 | share/python-wheels/
24 | *.egg-info/
25 | .installed.cfg
26 | *.egg
27 | MANIFEST
28 |
29 | # PyInstaller
30 | # Usually these files are written by a python script from a template
31 | # before PyInstaller builds the exe, so as to inject date/other infos into it.
32 | *.manifest
33 | *.spec
34 |
35 | # Installer logs
36 | pip-log.txt
37 | pip-delete-this-directory.txt
38 |
39 | # Unit test / coverage reports
40 | htmlcov/
41 | .tox/
42 | .nox/
43 | .coverage
44 | .coverage.*
45 | .cache
46 | nosetests.xml
47 | coverage.xml
48 | *.cover
49 | *.py.cover
50 | .hypothesis/
51 | .pytest_cache/
52 | cover/
53 |
54 | # Translations
55 | *.mo
56 | *.pot
57 |
58 | # Django stuff:
59 | *.log
60 | local_settings.py
61 | db.sqlite3
62 | db.sqlite3-journal
63 |
64 | # Flask stuff:
65 | instance/
66 | .webassets-cache
67 |
68 | # Scrapy stuff:
69 | .scrapy
70 |
71 | # Sphinx documentation
72 | docs/_build/
73 |
74 | # PyBuilder
75 | .pybuilder/
76 | target/
77 |
78 | # Jupyter Notebook
79 | .ipynb_checkpoints
80 |
81 | # IPython
82 | profile_default/
83 | ipython_config.py
84 |
85 | # pyenv
86 | # For a library or package, you might want to ignore these files since the code is
87 | # intended to run in multiple environments; otherwise, check them in:
88 | # .python-version
89 |
90 | # pipenv
91 | # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
92 | # However, in case of collaboration, if having platform-specific dependencies or dependencies
93 | # having no cross-platform support, pipenv may install dependencies that don't work, or not
94 | # install all needed dependencies.
95 | #Pipfile.lock
96 |
97 | # UV
98 | # Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
99 | # This is especially recommended for binary packages to ensure reproducibility, and is more
100 | # commonly ignored for libraries.
101 | #uv.lock
102 |
103 | # poetry
104 | # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
105 | # This is especially recommended for binary packages to ensure reproducibility, and is more
106 | # commonly ignored for libraries.
107 | # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
108 | #poetry.lock
109 | #poetry.toml
110 |
111 | # pdm
112 | # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
113 | # pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
114 | # https://pdm-project.org/en/latest/usage/project/#working-with-version-control
115 | #pdm.lock
116 | #pdm.toml
117 | .pdm-python
118 | .pdm-build/
119 |
120 | # pixi
121 | # Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
122 | #pixi.lock
123 | # Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
124 | # in the .venv directory. It is recommended not to include this directory in version control.
125 | .pixi
126 |
127 | # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
128 | __pypackages__/
129 |
130 | # Celery stuff
131 | celerybeat-schedule
132 | celerybeat.pid
133 |
134 | # SageMath parsed files
135 | *.sage.py
136 |
137 | # Environments
138 | .env
139 | .envrc
140 | .venv
141 | env/
142 | venv/
143 | ENV/
144 | env.bak/
145 | venv.bak/
146 |
147 | # Spyder project settings
148 | .spyderproject
149 | .spyproject
150 |
151 | # Rope project settings
152 | .ropeproject
153 |
154 | # mkdocs documentation
155 | /site
156 |
157 | # mypy
158 | .mypy_cache/
159 | .dmypy.json
160 | dmypy.json
161 |
162 | # Pyre type checker
163 | .pyre/
164 |
165 | # pytype static type analyzer
166 | .pytype/
167 |
168 | # Cython debug symbols
169 | cython_debug/
170 |
171 | # PyCharm
172 | # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
173 | # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
174 | # and can be added to the global gitignore or merged into this file. For a more nuclear
175 | # option (not recommended) you can uncomment the following to ignore the entire idea folder.
176 | #.idea/
177 |
178 | # Abstra
179 | # Abstra is an AI-powered process automation framework.
180 | # Ignore directories containing user credentials, local state, and settings.
181 | # Learn more at https://abstra.io/docs
182 | .abstra/
183 |
184 | # Visual Studio Code
185 | # Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
186 | # that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
187 | # and can be added to the global gitignore or merged into this file. However, if you prefer,
188 | # you could uncomment the following to ignore the entire vscode folder
189 | # .vscode/
190 |
191 | # Ruff stuff:
192 | .ruff_cache/
193 |
194 | # PyPI configuration file
195 | .pypirc
196 |
197 | # Cursor
198 | # Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
199 | # exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
200 | # refer to https://docs.cursor.com/context/ignore-files
201 | .cursorignore
202 | .cursorindexingignore
203 |
204 | # Marimo
205 | marimo/_static/
206 | marimo/_lsp/
207 | __marimo__/
208 |
--------------------------------------------------------------------------------
/demo/styles.css:
--------------------------------------------------------------------------------
1 | * {
2 | margin: 0;
3 | padding: 0;
4 | box-sizing: border-box;
5 | }
6 |
7 | body {
8 | font-family: 'Arial', sans-serif;
9 | background: #000;
10 | color: #fff;
11 | overflow: hidden;
12 | }
13 |
14 | #gameContainer {
15 | position: relative;
16 | width: 100vw;
17 | height: 100vh;
18 | }
19 |
20 | #gameCanvas {
21 | display: block;
22 | width: 100%;
23 | height: 100%;
24 | }
25 |
26 | /* UI Styles */
27 | #ui {
28 | position: absolute;
29 | top: 0;
30 | left: 0;
31 | width: 100%;
32 | height: 100%;
33 | pointer-events: none;
34 | z-index: 10;
35 | }
36 |
37 | #speedometer {
38 | position: absolute;
39 | bottom: 30px;
40 | right: 30px;
41 | text-align: center;
42 | background: rgba(0, 0, 0, 0.7);
43 | padding: 20px;
44 | border-radius: 10px;
45 | border: 2px solid #00ff00;
46 | }
47 |
48 | #speed {
49 | font-size: 48px;
50 | font-weight: bold;
51 | color: #00ff00;
52 | text-shadow: 0 0 10px #00ff00;
53 | }
54 |
55 | #speedUnit {
56 | font-size: 14px;
57 | color: #aaa;
58 | margin-top: 5px;
59 | }
60 |
61 | #position {
62 | position: absolute;
63 | top: 30px;
64 | right: 30px;
65 | background: rgba(0, 0, 0, 0.7);
66 | padding: 15px;
67 | border-radius: 10px;
68 | border: 2px solid #ffff00;
69 | }
70 |
71 | #positionText {
72 | font-size: 18px;
73 | color: #ffff00;
74 | font-weight: bold;
75 | }
76 |
77 | #lapTime {
78 | position: absolute;
79 | top: 30px;
80 | left: 30px;
81 | background: rgba(0, 0, 0, 0.7);
82 | padding: 15px;
83 | border-radius: 10px;
84 | border: 2px solid #00ffff;
85 | }
86 |
87 | #currentLap, #bestLap {
88 | font-size: 16px;
89 | color: #00ffff;
90 | margin: 5px 0;
91 | }
92 |
93 | #minimap {
94 | position: absolute;
95 | bottom: 30px;
96 | left: 30px;
97 | background: rgba(0, 0, 0, 0.7);
98 | padding: 10px;
99 | border-radius: 10px;
100 | border: 2px solid #ff00ff;
101 | }
102 |
103 | #minimapCanvas {
104 | border: 1px solid #ff00ff;
105 | border-radius: 5px;
106 | }
107 |
108 | #controls {
109 | position: absolute;
110 | bottom: 30px;
111 | left: 50%;
112 | transform: translateX(-50%);
113 | background: rgba(0, 0, 0, 0.7);
114 | padding: 15px;
115 | border-radius: 10px;
116 | border: 2px solid #ff6600;
117 | display: flex;
118 | gap: 20px;
119 | }
120 |
121 | .control-item {
122 | font-size: 12px;
123 | color: #ff6600;
124 | text-align: center;
125 | }
126 |
127 | /* Menu Styles */
128 | .menu {
129 | position: absolute;
130 | top: 0;
131 | left: 0;
132 | width: 100%;
133 | height: 100%;
134 | background: rgba(0, 0, 0, 0.9);
135 | display: flex;
136 | flex-direction: column;
137 | justify-content: center;
138 | align-items: center;
139 | z-index: 100;
140 | opacity: 0;
141 | visibility: hidden;
142 | transition: all 0.3s ease;
143 | }
144 |
145 | .menu.active {
146 | opacity: 1;
147 | visibility: visible;
148 | }
149 |
150 | .menu h1 {
151 | font-size: 48px;
152 | margin-bottom: 50px;
153 | text-shadow: 0 0 20px #00ff00;
154 | color: #00ff00;
155 | }
156 |
157 | .menu-buttons {
158 | display: flex;
159 | flex-direction: column;
160 | gap: 20px;
161 | }
162 |
163 | .menu-buttons button {
164 | padding: 15px 40px;
165 | font-size: 18px;
166 | background: linear-gradient(45deg, #00ff00, #00aa00);
167 | color: #000;
168 | border: none;
169 | border-radius: 5px;
170 | cursor: pointer;
171 | transition: all 0.3s ease;
172 | font-weight: bold;
173 | }
174 |
175 | .menu-buttons button:hover {
176 | background: linear-gradient(45deg, #00aa00, #00ff00);
177 | transform: scale(1.05);
178 | box-shadow: 0 0 20px #00ff00;
179 | }
180 |
181 | /* Loading Screen */
182 | .loading {
183 | position: absolute;
184 | top: 0;
185 | left: 0;
186 | width: 100%;
187 | height: 100%;
188 | background: rgba(0, 0, 0, 0.95);
189 | display: flex;
190 | flex-direction: column;
191 | justify-content: center;
192 | align-items: center;
193 | z-index: 200;
194 | opacity: 0;
195 | visibility: hidden;
196 | transition: all 0.3s ease;
197 | }
198 |
199 | .loading.active {
200 | opacity: 1;
201 | visibility: visible;
202 | }
203 |
204 | .loading-text {
205 | font-size: 24px;
206 | margin-bottom: 20px;
207 | color: #00ff00;
208 | }
209 |
210 | .loading-bar {
211 | width: 300px;
212 | height: 20px;
213 | background: rgba(255, 255, 255, 0.2);
214 | border-radius: 10px;
215 | overflow: hidden;
216 | border: 1px solid #00ff00;
217 | }
218 |
219 | .loading-progress {
220 | height: 100%;
221 | background: linear-gradient(90deg, #00ff00, #00aa00);
222 | width: 0%;
223 | transition: width 0.3s ease;
224 | }
225 |
226 | /* Responsive Design */
227 | @media (max-width: 768px) {
228 | #speedometer {
229 | bottom: 20px;
230 | right: 20px;
231 | padding: 15px;
232 | }
233 |
234 | #speed {
235 | font-size: 36px;
236 | }
237 |
238 | #position, #lapTime {
239 | top: 20px;
240 | padding: 10px;
241 | }
242 |
243 | #minimap {
244 | bottom: 20px;
245 | left: 20px;
246 | }
247 |
248 | #controls {
249 | bottom: 20px;
250 | flex-direction: column;
251 | gap: 10px;
252 | padding: 10px;
253 | }
254 |
255 | .menu h1 {
256 | font-size: 36px;
257 | }
258 |
259 | .menu-buttons button {
260 | padding: 12px 30px;
261 | font-size: 16px;
262 | }
263 | }
--------------------------------------------------------------------------------
/demo/js/track.js:
--------------------------------------------------------------------------------
1 | class Track {
2 | constructor() {
3 | this.width = 12;
4 | this.segments = [];
5 | this.barriers = [];
6 | this.checkpoints = [];
7 | this.startLine = null;
8 |
9 | this.generateTrack();
10 | this.generateBarriers();
11 | this.generateCheckpoints();
12 | }
13 |
14 | generateTrack() {
15 | const trackPoints = [
16 | new Vector3(0, 0, 0),
17 | new Vector3(0, 0, 50),
18 | new Vector3(30, 0, 80),
19 | new Vector3(60, 0, 80),
20 | new Vector3(90, 0, 50),
21 | new Vector3(90, 0, 0),
22 | new Vector3(60, 0, -30),
23 | new Vector3(30, 0, -30),
24 | new Vector3(0, 0, 0)
25 | ];
26 |
27 | for (let i = 0; i < trackPoints.length - 1; i++) {
28 | const start = trackPoints[i];
29 | const end = trackPoints[i + 1];
30 | const direction = end.subtract(start).normalize();
31 | const length = start.distance(end);
32 |
33 | this.segments.push({
34 | start: start,
35 | end: end,
36 | direction: direction,
37 | length: length,
38 | width: this.width
39 | });
40 | }
41 |
42 | this.startLine = {
43 | position: new Vector3(0, 0, -5),
44 | direction: new Vector3(0, 0, 1),
45 | width: this.width
46 | };
47 | }
48 |
49 | generateBarriers() {
50 | this.barriers = [];
51 |
52 | for (const segment of this.segments) {
53 | const leftBarrier = this.createBarrier(segment, -this.width / 2 - 1);
54 | const rightBarrier = this.createBarrier(segment, this.width / 2 + 1);
55 |
56 | this.barriers.push(leftBarrier, rightBarrier);
57 | }
58 | }
59 |
60 | createBarrier(segment, offset) {
61 | const perpendicular = new Vector3(-segment.direction.z, 0, segment.direction.x);
62 | const start = segment.start.add(perpendicular.multiply(offset));
63 | const end = segment.end.add(perpendicular.multiply(offset));
64 |
65 | return {
66 | start: start,
67 | end: end,
68 | height: 2,
69 | width: 0.5
70 | };
71 | }
72 |
73 | generateCheckpoints() {
74 | this.checkpoints = [];
75 |
76 | for (let i = 0; i < this.segments.length; i++) {
77 | const segment = this.segments[i];
78 | const midpoint = segment.start.add(segment.end).divide(2);
79 |
80 | this.checkpoints.push({
81 | position: midpoint,
82 | width: this.width,
83 | passed: false,
84 | index: i
85 | });
86 | }
87 | }
88 |
89 | getTrackBounds() {
90 | let minX = Infinity, maxX = -Infinity;
91 | let minZ = Infinity, maxZ = -Infinity;
92 |
93 | for (const segment of this.segments) {
94 | minX = Math.min(minX, segment.start.x, segment.end.x);
95 | maxX = Math.max(maxX, segment.start.x, segment.end.x);
96 | minZ = Math.min(minZ, segment.start.z, segment.end.z);
97 | maxZ = Math.max(maxZ, segment.start.z, segment.end.z);
98 | }
99 |
100 | return { minX, maxX, minZ, maxZ };
101 | }
102 |
103 | getTrackWidthAt(position) {
104 | return this.width;
105 | }
106 |
107 | getNearestTrackPoint(position) {
108 | let nearestPoint = null;
109 | let minDistance = Infinity;
110 |
111 | for (const segment of this.segments) {
112 | const point = this.getClosestPointOnSegment(position, segment);
113 | const distance = position.distance(point);
114 |
115 | if (distance < minDistance) {
116 | minDistance = distance;
117 | nearestPoint = point;
118 | }
119 | }
120 |
121 | return { point: nearestPoint, distance: minDistance };
122 | }
123 |
124 | getClosestPointOnSegment(point, segment) {
125 | const toStart = point.subtract(segment.start);
126 | const toEnd = segment.end.subtract(segment.start);
127 |
128 | const t = Math.max(0, Math.min(1, toStart.dot(toEnd) / toEnd.dot(toEnd)));
129 |
130 | return segment.start.add(toEnd.multiply(t));
131 | }
132 |
133 | isOnTrack(position) {
134 | const trackInfo = this.getNearestTrackPoint(position);
135 | return trackInfo.distance <= this.width / 2;
136 | }
137 |
138 | checkCollision(position, radius = 1) {
139 | for (const barrier of this.barriers) {
140 | if (this.checkBarrierCollision(position, barrier, radius)) {
141 | return true;
142 | }
143 | }
144 | return false;
145 | }
146 |
147 | checkBarrierCollision(position, barrier, radius) {
148 | const closestPoint = this.getClosestPointOnSegment(position, {
149 | start: barrier.start,
150 | end: barrier.end
151 | });
152 |
153 | return position.distance(closestPoint) < radius + barrier.width;
154 | }
155 |
156 | resetCheckpoints() {
157 | for (const checkpoint of this.checkpoints) {
158 | checkpoint.passed = false;
159 | }
160 | }
161 |
162 | checkLapComplete(carPosition) {
163 | if (!this.startLine) return false;
164 |
165 | const distanceToStart = carPosition.distance(this.startLine.position);
166 |
167 | if (distanceToStart < 5) {
168 | const allPassed = this.checkpoints.every(cp => cp.passed);
169 |
170 | if (allPassed) {
171 | this.resetCheckpoints();
172 | return true;
173 | }
174 | }
175 |
176 | return false;
177 | }
178 |
179 | updateCheckpoints(carPosition) {
180 | for (const checkpoint of this.checkpoints) {
181 | if (!checkpoint.passed) {
182 | const distance = carPosition.distance(checkpoint.position);
183 | if (distance < 8) {
184 | checkpoint.passed = true;
185 | }
186 | }
187 | }
188 | }
189 | }
--------------------------------------------------------------------------------
/demo/js/utils.js:
--------------------------------------------------------------------------------
1 | // Utility functions for the racing game
2 |
3 | class Vector3 {
4 | constructor(x = 0, y = 0, z = 0) {
5 | this.x = x;
6 | this.y = y;
7 | this.z = z;
8 | }
9 |
10 | clone() {
11 | return new Vector3(this.x, this.y, this.z);
12 | }
13 |
14 | add(v) {
15 | return new Vector3(this.x + v.x, this.y + v.y, this.z + v.z);
16 | }
17 |
18 | subtract(v) {
19 | return new Vector3(this.x - v.x, this.y - v.y, this.z - v.z);
20 | }
21 |
22 | multiply(scalar) {
23 | return new Vector3(this.x * scalar, this.y * scalar, this.z * scalar);
24 | }
25 |
26 | length() {
27 | return Math.sqrt(this.x * this.x + this.y * this.y + this.z * this.z);
28 | }
29 |
30 | normalize() {
31 | const len = this.length();
32 | if (len === 0) return new Vector3();
33 | return new Vector3(this.x / len, this.y / len, this.z / len);
34 | }
35 |
36 | dot(v) {
37 | return this.x * v.x + this.y * v.y + this.z * v.z;
38 | }
39 |
40 | cross(v) {
41 | return new Vector3(
42 | this.y * v.z - this.z * v.y,
43 | this.z * v.x - this.x * v.z,
44 | this.x * v.y - this.y * v.x
45 | );
46 | }
47 | }
48 |
49 | class MathUtils {
50 | static lerp(a, b, t) {
51 | return a + (b - a) * t;
52 | }
53 |
54 | static clamp(value, min, max) {
55 | return Math.max(min, Math.min(max, value));
56 | }
57 |
58 | static randomRange(min, max) {
59 | return Math.random() * (max - min) + min;
60 | }
61 |
62 | static degToRad(degrees) {
63 | return degrees * (Math.PI / 180);
64 | }
65 |
66 | static radToDeg(radians) {
67 | return radians * (180 / Math.PI);
68 | }
69 |
70 | static smoothstep(min, max, value) {
71 | const t = MathUtils.clamp((value - min) / (max - min), 0, 1);
72 | return t * t * (3 - 2 * t);
73 | }
74 | }
75 |
76 | class Color {
77 | constructor(r = 1, g = 1, b = 1) {
78 | this.r = r;
79 | this.g = g;
80 | this.b = b;
81 | }
82 |
83 | toHex() {
84 | const r = Math.floor(this.r * 255);
85 | const g = Math.floor(this.g * 255);
86 | const b = Math.floor(this.b * 255);
87 | return `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}`;
88 | }
89 |
90 | toString() {
91 | return `rgb(${Math.floor(this.r * 255)}, ${Math.floor(this.g * 255)}, ${Math.floor(this.b * 255)})`;
92 | }
93 | }
94 |
95 | // Input handling
96 | class InputManager {
97 | constructor() {
98 | this.keys = {};
99 | this.mouse = { x: 0, y: 0, buttons: {} };
100 | this.gamepad = null;
101 |
102 | this.setupEventListeners();
103 | }
104 |
105 | setupEventListeners() {
106 | document.addEventListener('keydown', (e) => {
107 | this.keys[e.code] = true;
108 | });
109 |
110 | document.addEventListener('keyup', (e) => {
111 | this.keys[e.code] = false;
112 | });
113 |
114 | document.addEventListener('mousemove', (e) => {
115 | this.mouse.x = e.clientX;
116 | this.mouse.y = e.clientY;
117 | });
118 |
119 | document.addEventListener('mousedown', (e) => {
120 | this.mouse.buttons[e.button] = true;
121 | });
122 |
123 | document.addEventListener('mouseup', (e) => {
124 | this.mouse.buttons[e.button] = false;
125 | });
126 |
127 | window.addEventListener('gamepadconnected', (e) => {
128 | this.gamepad = e.gamepad;
129 | });
130 |
131 | window.addEventListener('gamepaddisconnected', (e) => {
132 | if (this.gamepad && this.gamepad.index === e.gamepad.index) {
133 | this.gamepad = null;
134 | }
135 | });
136 | }
137 |
138 | isKeyPressed(key) {
139 | return !!this.keys[key];
140 | }
141 |
142 | getMovementInput() {
143 | return {
144 | forward: this.isKeyPressed('KeyW') || this.isKeyPressed('ArrowUp'),
145 | backward: this.isKeyPressed('KeyS') || this.isKeyPressed('ArrowDown'),
146 | left: this.isKeyPressed('KeyA') || this.isKeyPressed('ArrowLeft'),
147 | right: this.isKeyPressed('KeyD') || this.isKeyPressed('ArrowRight'),
148 | brake: this.isKeyPressed('Space'),
149 | boost: this.isKeyPressed('ShiftLeft') || this.isKeyPressed('ShiftRight')
150 | };
151 | }
152 |
153 | updateGamepad() {
154 | if (this.gamepad) {
155 | const gamepads = navigator.getGamepads();
156 | this.gamepad = gamepads[this.gamepad.index];
157 | }
158 | }
159 | }
160 |
161 | // Performance monitoring
162 | class PerformanceMonitor {
163 | constructor() {
164 | this.fps = 0;
165 | this.frameTime = 0;
166 | this.lastTime = performance.now();
167 | this.frameCount = 0;
168 | this.fpsUpdateTime = 0;
169 | }
170 |
171 | update() {
172 | const currentTime = performance.now();
173 | this.frameTime = currentTime - this.lastTime;
174 | this.lastTime = currentTime;
175 |
176 | this.frameCount++;
177 | this.fpsUpdateTime += this.frameTime;
178 |
179 | if (this.fpsUpdateTime >= 1000) {
180 | this.fps = Math.round(this.frameCount * 1000 / this.fpsUpdateTime);
181 | this.frameCount = 0;
182 | this.fpsUpdateTime = 0;
183 | }
184 | }
185 | }
186 |
187 | // Resource loading
188 | class ResourceManager {
189 | constructor() {
190 | this.textures = new Map();
191 | this.models = new Map();
192 | this.sounds = new Map();
193 | this.loadingProgress = 0;
194 | this.totalResources = 0;
195 | this.loadedResources = 0;
196 | }
197 |
198 | async loadTexture(name, url) {
199 | return new Promise((resolve, reject) => {
200 | const texture = new THREE.TextureLoader().load(
201 | url,
202 | () => {
203 | this.textures.set(name, texture);
204 | this.onResourceLoaded();
205 | resolve(texture);
206 | },
207 | undefined,
208 | reject
209 | );
210 | });
211 | }
212 |
213 | async loadModel(name, url) {
214 | return new Promise((resolve, reject) => {
215 | const loader = new THREE.GLTFLoader();
216 | loader.load(
217 | url,
218 | (gltf) => {
219 | this.models.set(name, gltf);
220 | this.onResourceLoaded();
221 | resolve(gltf);
222 | },
223 | undefined,
224 | reject
225 | );
226 | });
227 | }
228 |
229 | async loadSound(name, url) {
230 | return new Promise((resolve, reject) => {
231 | const audio = new Audio(url);
232 | audio.addEventListener('canplaythrough', () => {
233 | this.sounds.set(name, audio);
234 | this.onResourceLoaded();
235 | resolve(audio);
236 | });
237 | audio.addEventListener('error', reject);
238 | });
239 | }
240 |
241 | onResourceLoaded() {
242 | this.loadedResources++;
243 | this.loadingProgress = this.loadedResources / this.totalResources;
244 | }
245 |
246 | getTexture(name) {
247 | return this.textures.get(name);
248 | }
249 |
250 | getModel(name) {
251 | return this.models.get(name);
252 | }
253 |
254 | getSound(name) {
255 | return this.sounds.get(name);
256 | }
257 | }
258 |
259 | // Export for use in other modules
260 | if (typeof module !== 'undefined' && module.exports) {
261 | module.exports = {
262 | Vector3,
263 | MathUtils,
264 | Color,
265 | InputManager,
266 | PerformanceMonitor,
267 | ResourceManager
268 | };
269 | }
--------------------------------------------------------------------------------
/demo/catch_game.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 | Catch the Falling Objects
7 |
68 |
69 |
70 |
71 |
Catch the Falling Objects!
72 |
Use arrow keys or A/D to move the basket
73 |
Score: 0
74 |
75 |
Game Over! Final Score: 0
76 |
77 |
78 |
81 |
82 |
83 |
Score: 0
84 |
Speed: 0 km/h
85 |
86 |
87 | Use Arrow Keys to steer, Up Arrow to accelerate, Down Arrow to brake
88 |
89 |
90 |
Game Over!
91 |
Final Score: 0
92 |
93 |
94 |
五子棋盘上的贪吃蛇
148 |
149 |
150 |
151 |
152 |
153 |
154 |
155 | 得分: 0
156 | 长度: 3
157 |
158 |
161 |