本文档面向 Lucy 的内部维护者与贡献者，覆盖以下内容：

• 代码库结构与关键模块职责
• 本地开发的标准工作流
• 常见功能扩展的代码入口

建议在阅读本页前，先了解 架构总览。

lucy 仓库遵循标准 Go module 布局：

├── cmd/          # CLI 定义与命令处理器（urfave/cli）
├── probe/        # 服务端环境检测与拓扑构建
├── types/        # 核心领域模型与数据结构
├── exttype/      # 外部/第三方类型定义（如 Modrinth、MCDR schema）
├── install/      # 平台特定的安装逻辑
├── dependency/   # 版本解析与约束求解
├── upstream/     # 外部 API 客户端（Modrinth、CurseForge 等）
│   └── routing/  # 数据源选择与并行抓取逻辑
├── cache/        # 本地下载与元数据缓存
├── logger/       # 应用日志
└── tools/        # 共享工具函数

开发前请确保已安装 Task 与 Go 工具链，并在仓库根目录写入 CurseForge API 密钥：

# 在 lucy/ 根目录创建 .env 文件（该文件已被 .gitignore 忽略）
echo 'CF_API_KEY=your_key_here' > .env

# 构建 macOS arm64 开发版（输出到 dist/lucy-darwin-arm64-dev）
task build-dev

构建产物位于 dist/lucy-darwin-arm64-dev，包含 -tags debug 标记并保留完整符号信息，适合本地调试。

# 监听 .go 文件变化并执行增量重建（不会清空 dist/）
task build-watch

# 在任意 Minecraft 服务端目录中运行开发版
./dist/lucy-darwin-arm64-dev status

# 启用调试日志
./dist/lucy-darwin-arm64-dev --debug status

# 退出时打印完整日志历史
./dist/lucy-darwin-arm64-dev --print-logs add fabric/fabric-api@latest

# 输出日志文件路径并启用调试日志
./dist/lucy-darwin-arm64-dev -l --debug search carpet

# 运行全部测试
go test ./...

# 仅测试指定包
go test ./dependency/...

# 指定包测试（详细输出）
go test -v ./upstream/curseforge/...

# 清理开发版构建产物
task cleanup-dist

# 生成 bash / zsh / fish shell 补全脚本
task gen-completions

# 构建多平台 Release 版本（需要有效 CF_API_KEY）
task build-release

以下是最常见扩展点及其代码入口。

注册入口：cmd/cmd.go（参见第 54-61 行 Commands 数组）

Cli 变量定义了完整 CLI 入口，包括全局 flag、子命令列表和 shell 补全配置：

// ../lucy/cmd/cmd.go:18-69
// Cli is the main command for lucy
var Cli = &cli.Command{
 Name:  "lucy",
 Usage: "The Minecraft server-side package manager",
 Action: tools.Decorate(
  actionEmpty,
  decoratorBaseCommandFlags,
  decoratorGlobalFlags,
  decoratorHelpAndExitOnNoArg,
  decoratorHelpAndExitOnError,
 ),
 Flags: []cli.Flag{
  &cli.BoolFlag{
   Name:    flagLogFileName,
   Aliases: []string{"l"},
   Usage:   "Output the path to logfile",
   Value:   false,
  },
  &cli.BoolFlag{
   Name:  flagPrintLogsName,
   Usage: "Print logs to console",
   Value: false,
  },
  &cli.BoolFlag{
   Name:  flagDebugName,
   Usage: "Show debug logs",
   Value: false,
  },
  &cli.BoolFlag{
   Name:   flagDumpLogsName,
   Usage:  "Dump the log history to console before exit",
   Value:  false,
   Hidden: true,
  },
  flagNoStyle,
 },
 Commands: []*cli.Command{
  subcmdStatus,
  subcmdInfo,
  subcmdSearch,
  subcmdAdd,
  subcmdInit,
  subcmdCache,
 },
 // Shell completion scripts are generated at runtime via `lucy completion <shell>`.
 // Use `lucy completion bash|fish|pwsh|zsh`; `--generate-shell-completion` is internal.
 EnableShellCompletion:  true,
 Suggest:                true,
 UseShortOptionHandling: true,
 DefaultCommand:         "help",
 OnUsageError:           helpOnUsageError,
}

操作步骤：

1. 在 cmd/ 新建 cmd_<name>.go，定义 *cli.Command 和对应 Action。
2. 用 tools.Decorate 包装 action，挂载标准装饰器（错误处理、flag 解析等）。
3. 在 cmd/cmd.go 的 Cli.Commands 末尾追加新命令变量。

示例（新增 sync 命令）：

# 创建命令文件
touch cmd/cmd_sync.go

并在 cmd/cmd.go 中追加：

// cmd/cmd.go, Cli.Commands array
Commands: []*cli.Command{
    subcmdStatus,
    subcmdInfo,
    subcmdSearch,
    subcmdAdd,
    subcmdInit,
    subcmdCache,
    subcmdSync, // <- new
},

注册入口：install/install.go（参见第 18 行 registerInstaller）

操作步骤：

1. 在 types/ 中确认或新增平台常量。

2. 在 probe/ 中补充对应平台环境探测逻辑，并更新 RuntimeTopology。

3. 新建 install/install_<platform>.go，实现下列函数签名：

   type platformInstaller func(p types.Package) error

4. 在 install/install.go 顶层调用 registerInstaller，绑定平台常量与实现。

注册入口：upstream/routing/routing.go（参见第 46-51 行 providerBySource map）

操作步骤：

1. 在 upstream/ 下新建子包目录（例如 upstream/mysource/）。
2. 实现 upstream.Provider 接口（Search、Fetch、Information 等方法）。
3. 在 upstream/routing/routing.go 的 providerBySource 中添加 Source -> Provider 映射。
4. 若需参与自动路由（SourceAuto），按需更新 autoProviders 切片或 ResolveProviders 的 switch 分支。

可参考现有实现：upstream/modrinth/、upstream/curseforge/。

包路径：dependency/

以下事项在当前开发阶段仍处于未完成状态，贡献时请重点关注：

1. 本地安装方法：probe 包中包含 .lucy 目录检测占位符，本地安装状态管理尚未最终确定。
2. 流式处理改造：main.go 中有注释 REPLACE ALL io.ReadAll WITH STREAMING METHODS，大文件下载/读取的内存效率仍待优化。
3. 优先首次响应：upstream/routing/routing_execution.go 中 FirstFetch 当前为 panic("not implemented")；目标是首个 provider 成功即返回，而不是等待全部并行请求结束。
4. 服务端覆盖确认：install/install.go 在 Vanilla 平台安装场景下，若已存在服务端仍是直接报错，需补充用户确认流程。

• Lucy 基于 Charm 生态（bubbletea、lipgloss、huh、glamour）构建终端 UI。
• 输出风格应保持简洁且可读：信息性消息优先通过 logger 输出，交互式提示使用 huh。
• 必须遵循 --no-style flag，保证 CI/CD 环境可禁用样式输出并保持兼容。

• 架构总览
• 上游数据源
• 安装流水线