fcdev 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/CHANGELOG.md +61 -32
  2. package/README.md +17 -16
  3. package/docs/{02- → 01-}/345/221/275/344/273/244/350/241/214/344/270/216/346/236/204/345/273/272.md +14 -12
  4. package/docs/02-/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +89 -0
  5. package/docs/{06- → 03-}/345/217/215/346/261/207/347/274/226.md +13 -47
  6. package/docs/{07- → 04-}/345/210/233/345/273/272/345/214/205/344/270/216/346/250/241/346/235/277.md +1 -15
  7. package/docs/nes/{01-NES/347/233/256/346/240/207.md → 01-/345/274/200/345/217/221/346/214/207/345/215/227.md} +4 -9
  8. package/docs/sb2000/01-/345/274/200/345/217/221/346/214/207/345/215/227.md +25 -30
  9. package/docs/sb2000/02-/347/263/273/347/273/237/350/260/203/347/224/250/346/211/213/345/206/214.md +4 -4
  10. package/docs/sb2000/03-/347/241/254/344/273/266/350/257/264/346/230/216.md +5 -5
  11. package/package.json +5 -2
  12. package/src/build/bank-link-config.mjs +1 -1
  13. package/src/build/build-plan.mjs +1 -1
  14. package/src/build/program-builder.mjs +10 -5
  15. package/src/build/source-charset.mjs +111 -0
  16. package/src/cli/args-parser.mjs +1 -1
  17. package/src/cli/commands/debug-command.mjs +20 -58
  18. package/src/cli/commands/docs-command.mjs +2 -2
  19. package/src/cli/commands/run-command.mjs +36 -39
  20. package/src/cli/index.mjs +5 -5
  21. package/src/config/config-loader.mjs +2 -2
  22. package/src/disasm/disassembler.mjs +1 -1
  23. package/src/disasm/trace.mjs +4 -3
  24. package/src/docs/doc-index.mjs +1 -1
  25. package/src/docs/doc-topics.mjs +32 -38
  26. package/src/docs/index.mjs +1 -1
  27. package/src/emulator/debug-cli.mjs +48 -0
  28. package/src/emulator/emulator-launcher.mjs +107 -29
  29. package/src/emulator/emulator-locator.mjs +7 -7
  30. package/src/emulator/index.mjs +4 -3
  31. package/src/emulator/sb2000-session.mjs +104 -0
  32. package/src/targets/target-registry.mjs +9 -1
  33. package/targets/nes/lib/fcnes.lib +0 -0
  34. package/targets/nes/lib/nes-font.o +0 -0
  35. package/targets/nes/target.json +1 -1
  36. package/targets/sb2000/api-reference.md +2 -1
  37. package/targets/sb2000/examples-source.md +1330 -0
  38. package/targets/sb2000/lib/crt0.o +0 -0
  39. package/targets/sb2000/lib/sb2000.lib +0 -0
  40. package/targets/sb2000/symbols-reference.md +670 -0
  41. package/targets/sb2000/target.json +2 -1
  42. package/docs/01-/350/275/257/344/273/266/346/236/266/346/236/204/350/256/276/350/256/241.md +0 -163
  43. package/docs/03-/347/233/256/346/240/207/350/247/204/350/214/203.md +0 -123
  44. package/docs/04-cc65/345/267/245/345/205/267/351/223/276.md +0 -50
  45. package/docs/05-/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +0 -92
  46. package/docs/08-/346/265/213/350/257/225/344/270/216/351/252/214/350/257/201.md +0 -72
  47. package/docs/09-/345/217/221/345/270/203.md +0 -70
  48. package/docs/10-VS Code/346/211/251/345/261/225.md" +0 -131
  49. package/docs//345/276/205/345/212/236/345/244/207/345/277/230.md +0 -47
  50. package/docs//347/274/272/351/231/267/350/256/260/345/275/225.md +0 -10
  51. package/src/emulator/debug-client.mjs +0 -125
@@ -1,14 +1,14 @@
1
1
  // ------------------------------------------------------------------------
2
2
  // 名称:run-command.mjs
3
- // 说明:run 命令:构建程序后在模拟器里运行;--debug 时启动调试模式,由 debug 命令继续操作。
3
+ // 说明:run 命令:构建程序后在 Ember 里运行;--debug 时启动调试模式,由 debug 命令继续操作。
4
4
  // 作者:sungbin
5
5
  // 邮箱:sungbin@3578.cn
6
6
  // 日期:2026-11-10
7
- // 备注:运行方案由目标的 run 字段声明:rom 直接加载产物;firmware-disk 加载固件(fcdev.json 的 firmware),挂载磁盘镜像后复位。
8
- // firmware-disk 方案需要调试服务挂载镜像,挂载完成后用 live 命令转为自由运行(加 --debug 则保持调试模式)。
7
+ // 备注:运行方案由目标的 run 字段声明:rom 直接加载产物;firmware-disk(学习机)加载 fcdev.json 的 firmware 指定的固件,
8
+ // 把程序放进磁盘镜像挂到软驱并开机,自由模式再在 SB-DOS 里输入程序名运行,调试模式停在开机状态。
9
9
  // ------------------------------------------------------------------------
10
10
  import path from 'node:path';
11
- import { buildDiskImage, buildPath } from '../../build/index.mjs';
11
+ import { buildDiskImage, buildPath, createBuildPlan } from '../../build/index.mjs';
12
12
  import { DEFAULT_DEBUG_PORT, launchEmulator, locateEmulator } from '../../emulator/index.mjs';
13
13
  import { FcdevError } from '../../shared/index.mjs';
14
14
 
@@ -16,53 +16,50 @@ import { FcdevError } from '../../shared/index.mjs';
16
16
  * 执行 run 命令。
17
17
  * @param {{positionals: string[], options: {target?: string, debug: boolean, port?: number}, context: import('../index.mjs').CliContext}} input 参数与运行环境
18
18
  * @returns {Promise<number>} 退出码
19
- * @throws {FcdevError} 目标没有运行方案、找不到模拟器或构建失败
19
+ * @throws {FcdevError} 目标没有运行方案、学习机没有配置固件、找不到 Ember 或构建失败
20
20
  */
21
21
  export async function runRunCommand({ positionals, options, context }) {
22
22
  if (positionals.length > 1) {
23
23
  throw new FcdevError('run 只接受一个路径参数', { code: 'ARGUMENT_INVALID', hint: '用法:npx fcdev run [目录或文件]' });
24
24
  }
25
+ const input = { pathArg: positionals[0], cwd: context.cwd, targetOverride: options.target, env: context.env };
26
+ const { target, config } = createBuildPlan(input);
27
+ if (!target.run) {
28
+ throw new FcdevError(`目标 ${target.name} 没有运行方案`, { code: 'TARGET_NO_RUN' });
29
+ }
30
+ const withFirmware = target.run.mode === 'firmware-disk';
31
+ if (withFirmware && !config.firmware) {
32
+ throw new FcdevError(`${target.name} 目标运行需要固件,fcdev.json 里没有设置 firmware`, {
33
+ code: 'FIRMWARE_MISSING',
34
+ hint: '在 fcdev.json 里用 firmware 指向学习机的 BIOS 文件(iNES 格式),例如 "firmware": "SB2K_BIOS.NES"',
35
+ });
36
+ }
37
+ const emulator = locateEmulator({ configured: config.emulator, env: context.env });
38
+ const port = options.port ?? DEFAULT_DEBUG_PORT;
39
+
25
40
  const reporter = {
26
41
  log: (message) => context.stdout.write(`${message}\n`),
27
42
  write: (text) => context.stderr.write(text),
28
43
  };
29
- const { plan, result } = await buildPath(
30
- { pathArg: positionals[0], cwd: context.cwd, targetOverride: options.target, env: context.env },
31
- reporter,
32
- );
33
- const run = plan.target.run;
34
- if (!run) {
35
- throw new FcdevError(`目标 ${plan.target.name} 没有运行方案`, { code: 'TARGET_NO_RUN' });
36
- }
37
- const emulator = locateEmulator({ configured: plan.config.emulator, env: context.env });
38
- const port = options.port ?? DEFAULT_DEBUG_PORT;
39
-
40
- if (run.mode === 'rom') {
41
- const { pid, client } = await launchEmulator({ executable: emulator.executable, romFile: result.outputFile, debug: options.debug, port });
42
- client?.close();
43
- context.stdout.write(`已启动模拟器(进程 ${pid}),加载 ${result.outputFile}\n`);
44
- } else {
45
- if (!plan.config.firmware) {
46
- throw new FcdevError(`目标 ${plan.target.name} 的运行需要固件(BIOS)`, {
47
- code: 'FIRMWARE_MISSING',
48
- hint: '在 fcdev.json 里用 firmware 指定固件文件;fcdev 不提供任何 BIOS 或 ROM',
49
- });
50
- }
44
+ const { plan, result } = await buildPath(input, reporter);
45
+ let launch;
46
+ let description;
47
+ if (withFirmware) {
51
48
  const { imageFile } = buildDiskImage(plan, result);
52
- const { pid, client } = await launchEmulator({ executable: emulator.executable, romFile: plan.config.firmware, debug: true, port });
53
- try {
54
- for (const command of [`disk ${imageFile}`, 'reset', ...(options.debug ? [] : ['live'])]) {
55
- const reply = await client.send(command);
56
- if (!reply.ok) throw new FcdevError(`模拟器拒绝命令“${command}”:${reply.head}`, { code: 'EMULATOR_COMMAND_FAILED' });
57
- }
58
- } finally {
59
- client.close();
60
- }
61
- context.stdout.write(`已启动模拟器(进程 ${pid}),固件 ${plan.config.firmware},磁盘镜像 ${imageFile}\n`);
62
- context.stdout.write(`等 DOS 启动后,在提示符下输入 ${path.basename(result.outputFile, path.extname(result.outputFile))} 运行程序\n`);
49
+ const programName = path.basename(result.outputFile, path.extname(result.outputFile));
50
+ launch = { sb2000: { firmware: config.firmware, diskImage: imageFile, programName } };
51
+ description = `磁盘镜像 ${imageFile}(程序 ${programName})`;
52
+ } else {
53
+ launch = { romFile: result.outputFile };
54
+ description = result.outputFile;
63
55
  }
56
+ const { pid, client } = await launchEmulator({ executable: emulator.executable, ...launch, debug: options.debug, port });
57
+ client?.close();
58
+ context.stdout.write(`已启动 Ember(进程 ${pid}),加载 ${description}\n`);
64
59
  if (options.debug) {
65
- context.stdout.write(`调试模式:端口 ${port},模拟器只在收到 run 命令时运行,例如 npx fcdev debug run 60\n`);
60
+ context.stdout.write(withFirmware
61
+ ? `调试模式:端口 ${port},固件已加载、磁盘已放入软驱、整机已开机,但没有运行;程序要在 SB-DOS 里输入程序名才会运行,继续操作用 debug 命令,例如 npx fcdev debug call runtime.run frames=60 wait=true\n`
62
+ : `调试模式:端口 ${port},程序已载入并上电,但没有运行;继续操作用 debug 命令,例如 npx fcdev debug call runtime.run frames=60 wait=true\n`);
66
63
  }
67
64
  return 0;
68
65
  }
package/src/cli/index.mjs CHANGED
@@ -47,18 +47,18 @@ const HELP_TEXT = `fcdev:6502 兼容机的开发工具
47
47
 
48
48
  命令:
49
49
  build [目录或文件] 构建:无参数为当前目录;目录整体构成一个程序;文件单独构成一个程序
50
- run [目录或文件] 构建后在模拟器里运行(--debug 启动调试模式)
50
+ run [目录或文件] 构建后在 Ember 里运行(--debug 启动调试模式)
51
51
  disk [目录或文件] 构建后把程序放进磁盘镜像(只有支持磁盘的目标可用)
52
52
  disasm <文件> 反汇编 NES 程序或平铺二进制为 ca65 源码,并回读校验
53
- debug <命令> 把命令转发给模拟器的调试服务,如 debug run 60、debug shot out.png
53
+ debug <参数> 交给 Ember 调试 SDK 的终端客户端 ember-debug,如 debug call runtime.status、debug screenshot out.png
54
54
  sync 生成 IDE 的 C/C++ 配置
55
55
  info [--json] 显示目标、工具链与头文件目录
56
56
  api [词] [--json] 查询目标的 C 接口文档:函数名、模块名、$功能号或关键词;不带词列出全部模块
57
- docs [词] [--json] 查询开发文档:主题名或关键词,给出本机路径;不带词列出全部主题
57
+ docs [词] [--json] 查询使用文档:主题名或关键词,给出本机路径;不带词列出全部主题
58
58
 
59
59
  选项:
60
60
  --target <名> 指定目标,覆盖 fcdev.json
61
- --debug run 以调试模式启动模拟器
61
+ --debug run 以调试模式启动 Ember
62
62
  --port <端口> run 的调试端口,默认 5699;debug 命令读环境变量 FCDEV_DEBUG_PORT,默认也是 5699
63
63
  --json info 输出机器可读格式
64
64
 
@@ -67,7 +67,7 @@ disasm 的选项:
67
67
  --base <地址> 平铺二进制的加载地址(十六进制)
68
68
  --entry <地址> 追踪代码的入口,可重复;iNES 会自动使用中断向量
69
69
  --cdl <文件> CDL(FCEUX、Mesen 格式),代码段的起点也当作入口
70
- --trace <文件> 模拟器 trace 命令记录的指令轨迹,执行过的指令地址都当作入口
70
+ --trace <文件> Ember 的 inspector.traceStart(instruction)记录的指令轨迹,执行过的指令地址都当作入口
71
71
  --symbols <文件> 符号文件,每行“名字 = $地址”
72
72
  --out <目录> 输出目录,默认 build/disasm/<文件名>
73
73
  -h, --help 显示帮助
@@ -4,7 +4,7 @@
4
4
  // 作者:sungbin
5
5
  // 邮箱:sungbin@3578.cn
6
6
  // 日期:2026-11-10
7
- // 备注:未知的键直接报错,避免拼写错误被忽略;配置项含义见 docs/02-命令行与构建.md 第 3 节。
7
+ // 备注:未知的键直接报错,避免拼写错误被忽略;配置项含义见 packages/fcdev/docs/01-命令行与构建.md 第 3 节。
8
8
  // ------------------------------------------------------------------------
9
9
  import { existsSync } from 'node:fs';
10
10
  import path from 'node:path';
@@ -39,7 +39,7 @@ const KEY_TYPES = {
39
39
  * @property {string[]} include 额外头文件目录的绝对路径
40
40
  * @property {string|undefined} toolchain 自备 cc65 根目录的绝对路径
41
41
  * @property {string|undefined} firmware 固件文件的绝对路径
42
- * @property {string|undefined} emulator 自备模拟器路径
42
+ * @property {string|undefined} emulator Ember 可执行文件的路径
43
43
  * @property {Record<string, unknown>} targetOptions 目标专用选项
44
44
  */
45
45
 
@@ -47,7 +47,7 @@ function detectFormat(buffer, format) {
47
47
 
48
48
  /**
49
49
  * 反汇编一个文件,并回读校验。
50
- * @param {{inputFile: string, format?: string, base?: number, entries?: number[], cdlFile?: string, traceFile?: string, symbolsFile?: string, outDir: string, toolchain: import('../toolchain/index.mjs').Toolchain, includes?: string[]}} input 输入文件、格式、加载地址、入口、CDL、模拟器轨迹、符号文件、输出目录、工具链与 da65 要读的符号定义文件
50
+ * @param {{inputFile: string, format?: string, base?: number, entries?: number[], cdlFile?: string, traceFile?: string, symbolsFile?: string, outDir: string, toolchain: import('../toolchain/index.mjs').Toolchain, includes?: string[]}} input 输入文件、格式、加载地址、入口、CDL、Ember 轨迹、符号文件、输出目录、工具链与 da65 要读的符号定义文件
51
51
  * @returns {Promise<DisassemblyReport>} 报告
52
52
  * @throws {FcdevError} 输入不合法、da65 失败,或回读校验不一致
53
53
  */
@@ -1,14 +1,15 @@
1
1
  // ------------------------------------------------------------------------
2
2
  // 名称:trace.mjs
3
- // 说明:读取模拟器 trace 命令记录的指令轨迹:每行以 T 开头,第二列是执行到的指令地址。
3
+ // 说明:读取 Ember 的 inspector.traceStart(kind 为 instruction)记录的指令轨迹:每行是 nestest 日志的写法,行首是四位十六进制的指令地址。
4
4
  // 作者:sungbin
5
5
  // 邮箱:sungbin@3578.cn
6
6
  // 日期:2026-11-10
7
7
  // 备注:轨迹里的每个地址都是被真实执行过的指令开头,比 CDL 的“代码字节”更精确;用作追踪代码的入口。
8
+ // io、irq 与调用记录的行不是指令行,一律忽略;只认 Ember 的格式,不兼容旧模拟器的 T 行。
8
9
  // ------------------------------------------------------------------------
9
10
 
10
- /** 轨迹的一行:T、四位十六进制的指令地址,后面是物理地址、字节、寄存器 */
11
- const TRACE_LINE = /^T ([0-9A-Fa-f]{4}) /;
11
+ /** 指令行:四位十六进制的地址、两个空格,后面是至少一个两位十六进制的字节(调用记录的“8123 A:01”不符合) */
12
+ const TRACE_LINE = /^([0-9A-F]{4}) {2}[0-9A-F]{2}(?: |$)/;
12
13
 
13
14
  /**
14
15
  * 取出轨迹里被执行过的指令地址。
@@ -1,6 +1,6 @@
1
1
  // ------------------------------------------------------------------------
2
2
  // 名称:doc-index.mjs
3
- // 说明:开发文档的查询:列出全部主题,按主题名、文件名或关键词查找,给出每份文档的本机路径。
3
+ // 说明:使用文档的查询:列出全部主题,按主题名、文件名或关键词查找,给出每份文档的本机路径。
4
4
  // 作者:sungbin
5
5
  // 邮箱:sungbin@3578.cn
6
6
  // 日期:2026-11-11
@@ -1,38 +1,32 @@
1
- // ------------------------------------------------------------------------
2
- // 名称:doc-topics.mjs
3
- // 说明:开发文档的主题登记表:每份文档的主题名、相对 docs 目录的文件、标题和一句话说明。
4
- // 作者:sungbin
5
- // 邮箱:sungbin@3578.cn
6
- // 日期:2026-11-11
7
- // 备注:新增、改名或删除文档时同步改这里与 docs/01-软件架构设计.md 第 9 节;主题名只用小写字母、数字与连字符,便于在任何终端里输入。
8
- // ------------------------------------------------------------------------
9
-
10
- /**
11
- * @typedef {object} DocTopic
12
- * @property {string} topic 主题名
13
- * @property {string} file 文件路径,用 / 分隔;默认相对 docs 目录,`inPackage` 为 true 时相对主包根目录
14
- * @property {boolean} [inPackage] 文件不在 docs 目录里、而在主包其他目录下(如目标目录里由头文件生成的接口参考)
15
- * @property {string} title 标题
16
- * @property {string} summary 一句话说明
17
- */
18
-
19
- /** @type {DocTopic[]} */
20
- export const DOC_TOPICS = [
21
- { topic: 'architecture', file: '01-软件架构设计.md', title: '软件架构设计', summary: '包的划分、目录、分层规则、设计决策与文档清单' },
22
- { topic: 'build', file: '02-命令行与构建.md', title: '命令行与构建', summary: '命令、构建规则、配置文件 fcdev.json、构建流程' },
23
- { topic: 'targets', file: '03-目标规范.md', title: '目标规范', summary: '目标定义、打包器、新增机型的步骤' },
24
- { topic: 'toolchain', file: '04-cc65工具链.md', title: 'cc65 工具链', summary: 'cc65 源码、构建与工具链包' },
25
- { topic: 'emulator', file: '05-模拟器与调试.md', title: '模拟器与调试', summary: '运行方案、模拟器定位、调试服务与命令表' },
26
- { topic: 'disasm', file: '06-反汇编.md', title: '反汇编', summary: '反汇编前端的流程、输入与限制' },
27
- { topic: 'create', file: '07-创建包与模板.md', title: '创建包与模板', summary: 'npm create fcdev 的命令、模板与生成内容' },
28
- { topic: 'testing', file: '08-测试与验证.md', title: '测试与验证', summary: '测试分层、环境变量与运行方法' },
29
- { topic: 'release', file: '09-发布.md', title: '发布', summary: '发布顺序、前提与检查' },
30
- { topic: 'vscode', file: '10-VS Code扩展.md', title: 'VS Code 扩展', summary: '智能感知、语法高亮、项目信息来源、目录分层与打包' },
31
- { topic: 'nes', file: 'nes/01-NES目标.md', title: 'NES 目标', summary: 'NES 目标的内存与映射器、fcnes 函数、字库、运行' },
32
- { topic: 'sb2000', file: 'sb2000/01-开发指南.md', title: 'SB2000 开发指南', summary: '程序格式、内存布局、运行库、大程序换页、常用做法、易错点与示例' },
33
- { topic: 'syscall', file: 'sb2000/02-系统调用手册.md', title: 'SB-DOS 系统调用手册', summary: '系统调用的参数、结果、出错码与可靠程度' },
34
- { topic: 'hardware', file: 'sb2000/03-硬件说明.md', title: 'SB2000 硬件说明', summary: 'SB2000 的硬件行为与寄存器' },
35
- { topic: 'api', file: 'targets/sb2000/api-reference.md', inPackage: true, title: 'SB2000 C 接口参考', summary: '运行库全部函数的签名、参数、返回值与系统调用,由头文件文档注释生成,查询用 npx fcdev api' },
36
- { topic: 'todo', file: '待办备忘.md', title: '待办备忘', summary: '已确定以后再做的事项' },
37
- { topic: 'bugs', file: '缺陷记录.md', title: '缺陷记录', summary: '发现的缺陷及修复情况' },
38
- ];
1
+ // ------------------------------------------------------------------------
2
+ // 名称:doc-topics.mjs
3
+ // 说明:使用文档的主题登记表:每份文档的主题名、相对 docs 目录的文件、标题和一句话说明。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-11
7
+ // 备注:新增、改名或删除使用文档时同步改这里与仓库根目录 docs/01-软件架构设计.md 第 9 节;主题名只用小写字母、数字与连字符,便于在任何终端里输入。
8
+ // ------------------------------------------------------------------------
9
+
10
+ /**
11
+ * @typedef {object} DocTopic
12
+ * @property {string} topic 主题名
13
+ * @property {string} file 文件路径,用 / 分隔;默认相对 docs 目录,`inPackage` 为 true 时相对主包根目录
14
+ * @property {boolean} [inPackage] 文件不在 docs 目录里、而在主包其他目录下(如目标目录里由头文件生成的接口参考)
15
+ * @property {string} title 标题
16
+ * @property {string} summary 一句话说明
17
+ */
18
+
19
+ /** @type {DocTopic[]} */
20
+ export const DOC_TOPICS = [
21
+ { topic: 'build', file: '01-命令行与构建.md', title: '命令行与构建', summary: '命令、构建规则、配置文件 fcdev.json、构建流程' },
22
+ { topic: 'emulator', file: '02-模拟器与调试.md', title: '模拟器与调试', summary: '运行方案、Ember 定位、调试服务与 debug 命令' },
23
+ { topic: 'disasm', file: '03-反汇编.md', title: '反汇编', summary: '反汇编的命令、输入、追踪规则与限制' },
24
+ { topic: 'create', file: '04-创建包与模板.md', title: '创建包与模板', summary: 'npm create fcdev 的命令、模板与生成内容' },
25
+ { topic: 'nes', file: 'nes/01-开发指南.md', title: 'NES 开发指南', summary: 'NES 目标的内存与映射器、fcnes 函数、字库、运行' },
26
+ { topic: 'sb2000', file: 'sb2000/01-开发指南.md', title: 'SB2000 开发指南', summary: '程序格式、内存布局、运行库、大程序换页、常用做法、易错点与示例' },
27
+ { topic: 'examples', file: 'targets/sb2000/examples-source.md', inPackage: true, title: 'SB2000 示例程序源码', summary: '手册里提到的示例程序(hello、show、copy、pad、mouse、play 等)的完整源码,由示例项目生成' },
28
+ { topic: 'syscall', file: 'sb2000/02-系统调用手册.md', title: 'SB-DOS 系统调用手册', summary: '系统调用的参数、结果、出错码与可靠程度' },
29
+ { topic: 'hardware', file: 'sb2000/03-硬件说明.md', title: 'SB2000 硬件说明', summary: 'SB2000 的硬件行为与寄存器' },
30
+ { topic: 'api', file: 'targets/sb2000/api-reference.md', inPackage: true, title: 'SB2000 C 接口参考', summary: '运行库全部函数的签名、参数、返回值与系统调用,由头文件文档注释生成,查询用 npx fcdev api' },
31
+ { topic: 'symbols', file: 'targets/sb2000/symbols-reference.md', inPackage: true, title: 'SB2000 符号参考', summary: '功能号、子功能号、系统变量地址、出错码、硬件寄存器与位、运行库入口的汇编名与 C 名,由 sb2000.inc 生成' },
32
+ ];
@@ -1,6 +1,6 @@
1
1
  // ------------------------------------------------------------------------
2
2
  // 名称:index.mjs
3
- // 说明:docs 目录的对外入口:开发文档的主题登记与查询。
3
+ // 说明:docs 目录的对外入口:使用文档的主题登记与查询。
4
4
  // 作者:sungbin
5
5
  // 邮箱:sungbin@3578.cn
6
6
  // 日期:2026-11-11
@@ -0,0 +1,48 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:debug-cli.mjs
3
+ // 说明:debug 命令的底层:找到调试 SDK 随包提供的终端客户端 ember-debug,并决定它找 Ember 调试服务的环境变量。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-15
7
+ // 备注:fcdev 自己不实现任何调试命令,全部交给 ember-debug;没有显式指定地址、令牌、端点文件或用户数据目录时,
8
+ // 按调试端口(环境变量 FCDEV_DEBUG_PORT,默认 5699)找到 fcdev 用 run --debug 启动的那个 Ember。
9
+ // ------------------------------------------------------------------------
10
+ import { existsSync } from 'node:fs';
11
+ import { fileURLToPath } from 'node:url';
12
+ import { FcdevError } from '../shared/index.mjs';
13
+ import { DEFAULT_DEBUG_PORT, debugUserDataDirectory } from './emulator-launcher.mjs';
14
+
15
+ /** 用户显式指定调试服务位置的环境变量,设置了任何一个就不再按端口推算 */
16
+ const EXPLICIT_ENV_NAMES = ['EMBER_DEBUG_URL', 'EMBER_DEBUG_TOKEN', 'EMBER_DEBUG_ENDPOINT', 'EMBER_USER_DATA'];
17
+
18
+ /**
19
+ * 调试 SDK 的终端客户端(ember-debug)的入口文件。
20
+ * @returns {string} 入口文件的绝对路径
21
+ * @throws {FcdevError} SDK 没有安装或没有构建
22
+ */
23
+ export function resolveDebugCli() {
24
+ let file = null;
25
+ try {
26
+ file = fileURLToPath(new URL('./cli.js', import.meta.resolve('ember-debug-sdk')));
27
+ } catch {
28
+ // 下面统一报错
29
+ }
30
+ if (file === null || !existsSync(file)) {
31
+ throw new FcdevError('找不到调试 SDK(ember-debug-sdk)的终端客户端', {
32
+ code: 'DEBUG_SDK_MISSING',
33
+ hint: '在本仓库里先运行 npm run build -w packages/ember-debug-sdk;用 npm 安装的 fcdev 会自带',
34
+ });
35
+ }
36
+ return file;
37
+ }
38
+
39
+ /**
40
+ * 运行终端客户端时用的环境变量。
41
+ * @param {NodeJS.ProcessEnv} env 当前环境变量
42
+ * @returns {NodeJS.ProcessEnv} 新的环境变量;没有显式指定位置时加上 fcdev 启动的 Ember 的用户数据目录
43
+ */
44
+ export function debugEnvironment(env) {
45
+ if (EXPLICIT_ENV_NAMES.some((name) => env[name])) return env;
46
+ const port = Number(env.FCDEV_DEBUG_PORT) || DEFAULT_DEBUG_PORT;
47
+ return { ...env, EMBER_USER_DATA: debugUserDataDirectory(port) };
48
+ }
@@ -1,18 +1,26 @@
1
1
  // ------------------------------------------------------------------------
2
2
  // 名称:emulator-launcher.mjs
3
- // 说明:启动模拟器:自由运行模式直接打开窗口,调试模式设置调试端口并等待服务就绪。
3
+ // 说明:启动 Ember:自由运行模式直接打开窗口加载程序;调试模式用独立的用户数据目录与调试端口启动,连上调试服务后载入程序并停在开机状态。
4
4
  // 作者:sungbin
5
5
  // 邮箱:sungbin@3578.cn
6
6
  // 日期:2026-11-10
7
- // 备注:模拟器进程与命令行脱离,命令行退出后窗口保持打开;调试模式下模拟器只在收到 run 命令时才运行。
7
+ // 备注:Ember 进程与命令行脱离,命令行退出后窗口保持打开;调试模式不带 --cartridge,等连上调试服务后用 cartridges.load 载入并只上电不运行,由 debug 命令继续。
8
+ // 学习机(sb2000 参数)没有命令行入口,两种模式都经调试服务:添加固件、放入磁盘镜像、整机开机;自由模式再在 SB-DOS 里输入程序名并继续运行后断开,
9
+ // 调试模式停在开机状态(磁盘里的程序还没有被运行,由 debug 命令操作)。
10
+ // 调试服务的 SDK(ember-debug-sdk)只在需要连接时才加载,没有构建时只影响调试模式与学习机。
8
11
  // ------------------------------------------------------------------------
9
12
  import { spawn } from 'node:child_process';
10
- import { existsSync } from 'node:fs';
13
+ import { randomBytes } from 'node:crypto';
14
+ import { existsSync, mkdirSync, rmSync } from 'node:fs';
11
15
  import net from 'node:net';
16
+ import { tmpdir } from 'node:os';
12
17
  import path from 'node:path';
13
18
  import { setTimeout as delay } from 'node:timers/promises';
14
19
  import { FcdevError } from '../shared/index.mjs';
15
- import { DEFAULT_DEBUG_PORT, DebugClient } from './debug-client.mjs';
20
+ import { bootSb2000, enterProgram } from './sb2000-session.mjs';
21
+
22
+ /** fcdev 的调试服务默认端口 */
23
+ export const DEFAULT_DEBUG_PORT = 5699;
16
24
 
17
25
  /** 等待调试服务就绪的上限,单位毫秒 */
18
26
  const READY_TIMEOUT_MS = 30_000;
@@ -20,8 +28,21 @@ const READY_TIMEOUT_MS = 30_000;
20
28
  /** 轮询调试服务的间隔,单位毫秒 */
21
29
  const READY_POLL_MS = 300;
22
30
 
31
+ /** 调试服务连接名,显示在 Ember 的连接列表里 */
32
+ const CLIENT_NAME = 'fcdev';
33
+
34
+ /**
35
+ * 调试模式下 Ember 使用的用户数据目录:每个端口一个,与用户平时使用的 Ember 互不影响(单实例锁与设置都按用户数据目录区分)。
36
+ * @param {number} port 调试端口
37
+ * @param {string} [base] 上级目录,默认是系统临时目录
38
+ * @returns {string} 目录
39
+ */
40
+ export function debugUserDataDirectory(port, base = tmpdir()) {
41
+ return path.join(base, 'fcdev-ember', String(port));
42
+ }
43
+
23
44
  /**
24
- * 确认本机端口空闲。端口被占用时模拟器的调试服务会静默启动失败,客户端反而可能连到别的模拟器。
45
+ * 确认本机端口空闲。端口被占用时 Ember 的调试服务不会启动,客户端反而可能连到别的 Ember。
25
46
  * @param {number} port 端口
26
47
  * @returns {Promise<void>}
27
48
  * @throws {FcdevError} 端口已被占用
@@ -31,7 +52,7 @@ export function assertPortFree(port) {
31
52
  const server = net.createServer();
32
53
  server.once('error', (error) => reject(new FcdevError(`端口 ${port} 已被占用`, {
33
54
  code: 'EMULATOR_PORT_BUSY',
34
- hint: '用 --port 换一个端口,或关闭占用它的模拟器',
55
+ hint: '用 --port 换一个端口,或关闭占用它的 Ember',
35
56
  cause: error,
36
57
  })));
37
58
  server.listen(port, '127.0.0.1', () => server.close(() => resolve()));
@@ -39,42 +60,99 @@ export function assertPortFree(port) {
39
60
  }
40
61
 
41
62
  /**
42
- * 启动模拟器。
43
- * @param {{executable: string, romFile: string, debug?: boolean, port?: number, readyTimeoutMs?: number}} input 模拟器程序、要加载的文件、是否调试模式与端口
44
- * @returns {Promise<{pid: number|undefined, client: DebugClient|null}>} 进程号;调试模式下还有已连接的客户端,调用者负责关闭
45
- * @throws {FcdevError} 文件不存在、无法启动,或调试服务没有在时限内就绪
63
+ * 加载调试 SDK 的 Node 入口。
64
+ * @returns {Promise<typeof import('ember-debug-sdk/node')>} SDK 的 Node 入口
65
+ * @throws {FcdevError} SDK 没有构建
46
66
  */
47
- export async function launchEmulator({ executable, romFile, debug = false, port = DEFAULT_DEBUG_PORT, readyTimeoutMs = READY_TIMEOUT_MS }) {
48
- if (!existsSync(romFile)) throw new FcdevError(`找不到要加载的文件:${romFile}`, { code: 'EMULATOR_FILE_MISSING' });
49
- if (debug) await assertPortFree(port);
50
- const env = { ...process.env };
51
- if (debug) env.FCDEV_DEBUG_PORT = String(port);
52
- else delete env.FCDEV_DEBUG_PORT;
67
+ async function loadSdk() {
68
+ try {
69
+ return await import('ember-debug-sdk/node');
70
+ } catch (error) {
71
+ if (error?.code === 'ERR_MODULE_NOT_FOUND' || error?.code === 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
72
+ throw new FcdevError('找不到调试 SDK(ember-debug-sdk)的构建产物', {
73
+ code: 'DEBUG_SDK_MISSING',
74
+ hint: '在本仓库里先运行 npm run build -w packages/ember-debug-sdk;用 npm 安装的 fcdev 会自带',
75
+ cause: error,
76
+ });
77
+ }
78
+ throw error;
79
+ }
80
+ }
53
81
 
54
- const child = spawn(executable, [romFile], { cwd: path.dirname(executable), env, stdio: 'ignore', detached: true });
55
- const failure = new Promise((_, reject) => {
56
- child.once('error', (error) => reject(new FcdevError(`无法启动模拟器 ${executable}`, { code: 'EMULATOR_START_FAILED', cause: error })));
57
- });
58
- child.unref();
59
- if (!debug) {
82
+ /**
83
+ * 启动 Ember。
84
+ * @param {object} input 启动参数
85
+ * @param {string} input.executable Ember 程序
86
+ * @param {string} [input.romFile] 要加载的 .nes 文件(经典 FC);与 sb2000 二选一
87
+ * @param {{firmware: string, diskImage: string, programName?: string}} [input.sb2000] 学习机:固件(BIOS)、磁盘镜像,以及自由模式里要在 SB-DOS 运行的程序名
88
+ * @param {boolean} [input.debug] 是否调试模式
89
+ * @param {number} [input.port] 调试端口
90
+ * @param {number} [input.readyTimeoutMs] 等待调试服务就绪的上限
91
+ * @returns {Promise<{pid: number|undefined, client: import('ember-debug-sdk').EmberDebugClient|null}>} 进程号;调试模式下还有已连接的客户端,调用者负责关闭
92
+ * @throws {FcdevError} 文件不存在、无法启动、Ember 提前退出、拒绝载入,或调试服务没有在时限内就绪
93
+ */
94
+ export async function launchEmulator({ executable, romFile, sb2000, debug = false, port = DEFAULT_DEBUG_PORT, readyTimeoutMs = READY_TIMEOUT_MS }) {
95
+ if (romFile !== undefined && !existsSync(romFile)) throw new FcdevError(`找不到要加载的文件:${romFile}`, { code: 'EMULATOR_FILE_MISSING' });
96
+ const cwd = path.dirname(executable);
97
+
98
+ if (!debug && sb2000 === undefined) {
99
+ const child = spawn(executable, [`--cartridge=${romFile}`], { cwd, stdio: 'ignore', detached: true });
100
+ const failure = new Promise((_, reject) => {
101
+ child.once('error', (error) => reject(new FcdevError(`无法启动 Ember ${executable}`, { code: 'EMULATOR_START_FAILED', cause: error })));
102
+ });
103
+ child.unref();
60
104
  // 给启动失败留出报错的机会,再返回
61
105
  await Promise.race([failure, delay(300)]);
62
106
  return { pid: child.pid, client: null };
63
107
  }
64
108
 
109
+ const { connectToEmber } = await loadSdk();
110
+ await assertPortFree(port);
111
+ const userDataDirectory = debugUserDataDirectory(port);
112
+ mkdirSync(userDataDirectory, { recursive: true });
113
+ // 上一次会话遗留的端点文件,不能让客户端读到
114
+ rmSync(path.join(userDataDirectory, 'run', 'debug-endpoint.json'), { force: true });
115
+ const token = randomBytes(16).toString('hex');
116
+ const child = spawn(executable, [`--user-data-dir=${userDataDirectory}`, `--debug-port=${port}`, `--debug-token=${token}`], { cwd, stdio: 'ignore', detached: true });
117
+ const failure = new Promise((_, reject) => {
118
+ child.once('error', (error) => reject(new FcdevError(`无法启动 Ember ${executable}`, { code: 'EMULATOR_START_FAILED', cause: error })));
119
+ child.once('exit', (code) => reject(new FcdevError(`Ember 启动后退出了(退出码 ${code})`, { code: 'EMULATOR_START_FAILED', hint: '检查可执行文件是否是 Ember,以及端口是否被占用' })));
120
+ });
121
+ // 启动成功之后 Ember 退出也会让 failure 失败,没有人等它时不能算未处理的拒绝
122
+ failure.catch(() => {});
123
+ child.unref();
124
+
65
125
  const deadline = Date.now() + readyTimeoutMs;
66
126
  while (Date.now() < deadline) {
67
127
  try {
68
- const client = await Promise.race([DebugClient.connect({ port, timeoutMs: 1000 }), failure]);
69
- const status = await client.send('status');
70
- if (status.head.includes('running=1')) return { pid: child.pid, client };
71
- client.close();
128
+ const client = await Promise.race([connectToEmber({ userDataDirectory, clientName: CLIENT_NAME, connectTimeoutMs: 1000 }), failure]);
129
+ try {
130
+ if (sb2000 === undefined) {
131
+ await client.request('cartridges.load', { path: romFile, powerOn: true, resume: false });
132
+ } else {
133
+ await bootSb2000(client, sb2000);
134
+ if (!debug && sb2000.programName !== undefined) {
135
+ await enterProgram(client, sb2000.programName);
136
+ await client.request('runtime.resume', {});
137
+ }
138
+ }
139
+ } catch (error) {
140
+ client.close();
141
+ child.kill();
142
+ if (error instanceof FcdevError) throw error;
143
+ throw new FcdevError(`Ember 无法载入 ${romFile ?? sb2000.diskImage}:${error.message}`, { code: 'EMULATOR_LOAD_FAILED', cause: error });
144
+ }
145
+ if (!debug) {
146
+ client.close();
147
+ return { pid: child.pid, client: null };
148
+ }
149
+ return { pid: child.pid, client };
72
150
  } catch (error) {
73
- if (error.code === 'EMULATOR_START_FAILED') throw error;
74
- // 服务尚未就绪,稍后重试
151
+ if (error instanceof FcdevError) throw error;
152
+ // 调试服务尚未就绪(端点文件还没写出、连接被拒绝),稍后重试
75
153
  }
76
154
  await delay(READY_POLL_MS);
77
155
  }
78
156
  child.kill();
79
- throw new FcdevError(`等待模拟器的调试服务(端口 ${port})就绪超时`, { code: 'EMULATOR_NOT_READY', hint: '检查端口是否被占用,或先关闭已打开的模拟器' });
157
+ throw new FcdevError(`等待 Ember 的调试服务(端口 ${port})就绪超时`, { code: 'EMULATOR_NOT_READY', hint: '检查端口是否被占用' });
80
158
  }
@@ -1,6 +1,6 @@
1
1
  // ------------------------------------------------------------------------
2
2
  // 名称:emulator-locator.mjs
3
- // 说明:定位模拟器程序:配置项、环境变量,按顺序查找。
3
+ // 说明:定位 Ember(模拟器)的可执行文件:配置项、环境变量,按顺序查找,不去 PATH 里猜。
4
4
  // 作者:sungbin
5
5
  // 邮箱:sungbin@3578.cn
6
6
  // 日期:2026-11-10
@@ -10,25 +10,25 @@ import { existsSync } from 'node:fs';
10
10
  import path from 'node:path';
11
11
  import { FcdevError } from '../shared/index.mjs';
12
12
 
13
- /** 环境变量:模拟器的路径 */
13
+ /** 环境变量:Ember 可执行文件的路径 */
14
14
  export const EMULATOR_ENV_NAME = 'FCDEV_EMULATOR';
15
15
 
16
16
  /**
17
- * 按顺序定位模拟器:配置项 emulator、环境变量。
17
+ * 按顺序定位 Ember:配置项 emulator、环境变量。
18
18
  * @param {{configured?: string, env?: NodeJS.ProcessEnv}} [options] configured 为配置里的绝对路径
19
- * @returns {{executable: string, source: string}} 模拟器程序与来源
19
+ * @returns {{executable: string, source: string}} Ember 可执行文件与来源
20
20
  * @throws {FcdevError} 都找不到
21
21
  */
22
22
  export function locateEmulator({ configured, env = process.env } = {}) {
23
23
  const explicit = configured ? { executable: configured, source: 'config' } : env[EMULATOR_ENV_NAME] ? { executable: path.resolve(env[EMULATOR_ENV_NAME]), source: 'env' } : null;
24
24
  if (explicit) {
25
25
  if (!existsSync(explicit.executable)) {
26
- throw new FcdevError(`找不到模拟器:${explicit.executable}`, { code: 'EMULATOR_NOT_FOUND' });
26
+ throw new FcdevError(`找不到 Ember:${explicit.executable}`, { code: 'EMULATOR_NOT_FOUND' });
27
27
  }
28
28
  return explicit;
29
29
  }
30
- throw new FcdevError('找不到模拟器', {
30
+ throw new FcdevError('找不到 Ember', {
31
31
  code: 'EMULATOR_NOT_FOUND',
32
- hint: `任选一种:设置环境变量 ${EMULATOR_ENV_NAME} 指向模拟器程序;在 fcdev.json 里用 emulator 指定`,
32
+ hint: `任选一种:设置环境变量 ${EMULATOR_ENV_NAME} 指向 Ember 的可执行文件;在 fcdev.json 里用 emulator 指定`,
33
33
  });
34
34
  }
@@ -1,11 +1,12 @@
1
1
  // ------------------------------------------------------------------------
2
2
  // 名称:index.mjs
3
- // 说明:emulator 目录的对外入口:定位模拟器、启动模拟器、调试服务客户端。
3
+ // 说明:emulator 目录的对外入口:定位 Ember、启动 Ember、调试 SDK 终端客户端的定位。
4
4
  // 作者:sungbin
5
5
  // 邮箱:sungbin@3578.cn
6
6
  // 日期:2026-11-10
7
7
  // 备注:无
8
8
  // ------------------------------------------------------------------------
9
- export { DEFAULT_DEBUG_PORT, DebugClient, parseReply } from './debug-client.mjs';
10
- export { assertPortFree, launchEmulator } from './emulator-launcher.mjs';
9
+ export { debugEnvironment, resolveDebugCli } from './debug-cli.mjs';
10
+ export { DEFAULT_DEBUG_PORT, assertPortFree, debugUserDataDirectory, launchEmulator } from './emulator-launcher.mjs';
11
11
  export { EMULATOR_ENV_NAME, locateEmulator } from './emulator-locator.mjs';
12
+ export { DOS_PROMPT_FRAMES, SB2000_MACHINE, bootSb2000, enterProgram, keyCodeOf, runFrames, tapKey } from './sb2000-session.mjs';