[Backlog] 命令行CLI vs Web界面及服务端

项目链接：https://github.com/MrLesk/Backlog.md

前文：[Andrej Karpathy] 大型语言模型作为新型操作系统

Andrej Karpathy 在演讲中，有提到将人的可读数据格式 AI 可读化的重要性，以此来更好的提升AI处理的效果。

Backlog 就化繁为简的借助git，实现了md格式的任务管理，或许之后这种透明，简洁，机器友好的工作流会成为一种AI时代下的趋势。

docs：Backlog.md

Backlog.md 是一款直接集成在Git仓库中运行的任务管理工具。

通过简单的**Markdown文件管理任务、草稿、文档和决策，
支持通过强大的命令行界面（CLI）或轻量级Web界面**进行操作，

同时通过Git完整记录项目历史轨迹。

在这里插入图片描述

核心章节

架构

在这里插入图片描述

第1章：命令行界面（CLI）

欢迎来到Backlog.md的第一章！

我们将从探索与项目交互的主要方式开始——命令行界面（Command Line Interface，简称CLI）。

在这里插入图片描述

什么是命令行界面（CLI）？

想象计算机上有一个特殊的窗口，我们可以通过输入指令而非点击按钮来操作。

这个窗口就是终端（或命令提示符），在此输入指令即为使用命令行界面。

这如同用文本直接向计算机下达指令。在Backlog.md中，CLI让我们仅需输入文字即可管理项目的任务、文档和决策。

为何选择CLI？

高效：掌握命令后操作速度常快于菜单导航
强大：可执行图形界面无法完成的操作，支持任务自动化
灵活：完美适配其他工具和脚本

首个Backlog.md命令

我们从创建新项目元素开始。在Backlog.md中，可通过CLI创建任务来跟踪待办事项：

backlog task create "我的首个任务"

在终端输入该命令后：

调用backlog程序
指定主操作task
定义具体操作create
提供必要信息"我的首个任务"作为任务标题

Backlog.md将在项目中创建专属文件，终端显示类似反馈：
在这里插入图片描述

通过选项可添加更多细节：

backlog task create "带描述的任务" --description "此处需补充详细信息！"

其中--description是提供附加信息的选项参数，选项通常以--或-开头。

在这里插入图片描述

常用CLI操作示例：

列出任务：backlog task list
查看指定任务：backlog task view task-1
任务看板视图：backlog board view

在这里插入图片描述
（好像还没有兼容中文，所以任务就显示？？？？了qwq)

命令通用格式：backlog <主命令> <子命令> [选项]

CLI工作机制（底层解析）

执行backlog task create "新任务"时，计算机内部流程如下：

在这里插入图片描述

完整流程解析：

用户在终端输入命令
终端识别backlog程序并传递完整指令
CLI处理模块(src/cli.ts)使用Commander.js解析命令结构
核心协调器生成唯一ID并协调文件创建
文件系统操作执行磁盘写入
结果通过调用链返回终端显示

CLI核心代码解析

查看src/cli.ts中处理task create的简化代码：

// src/cli.ts (简化片段)
import { Command } from "commander"; // 命令解析库
import { Core } from "./index.ts"; // Backlog.md核心逻辑

const program = new Command();
const taskCmd = program.command("task"); // 定义'task'主命令

taskCmd
    .command("create <title>") // 定义'create'子命令
    .description("创建新任务")
    .action(async (title: string, options) => {
        const cwd = process.cwd(); // 获取当前项目目录
        const core = new Core(cwd); // 初始化核心模块

        const id = await generateNextId(core, options.parent); // 生成唯一ID
        const task = buildTaskFromOptions(id, title, options); // 构建任务对象

        const filepath = await core.createTask(task); // 核心创建逻辑
        
        console.log(`已创建任务 ${id}`); 
        console.log(`文件路径: ${filepath}`);
    });

program.parseAsync(process.argv); // 启动命令解析

该代码段展示如何通过Commander.js定义命令，并与核心模块交互完成实际任务创建。测试用例(src/test/cli.test.ts)验证CLI功能：

// src/test/cli.test.ts (简化片段)
describe("CLI集成测试", () => {
    it("应成功创建任务文件", async () => {
        const result = Bun.spawnSync([
            "bun", CLI_PATH, "task", "create", "CLI测试任务"
        ], { cwd: TEST_DIR });

        const out = result.stdout.toString();
        expect(out).toContain("已创建任务 task-1");
        
        const core = new Core(TEST_DIR);
        const task = await core.filesystem.loadTask("task-1");
        expect(task?.title).toBe("CLI测试任务");
    });
});

总结

本章我们掌握了Backlog.md命令行界面（CLI）的核心使用方法，理解其通过核心协调器协调文件系统操作实现任务创建的技术路径。

CLI虽高效强大，但并非唯一交互方式。下一章将探索另一种核心界面——Web服务端。

Web界面及服务端

第2章：Web界面及服务端

在第1章：命令行界面（CLI）中，我们掌握了通过终端命令与Backlog.md交互的方式。这种方式在快速操作和自动化场景中具有显著优势。

但有时我们可能更倾向于可视化操作界面。

想象将任务像便利贴般排列在看板上，轻松拖拽即可变更任务状态——这正是Backlog.md Web界面提供的核心功能！

什么是Web界面及服务端？

Web界面可视为通过命令行启动的本地微型网站，包含两大核心组件：

服务端：运行于本地的后台进程，作为数据处理中枢。负责与核心协调器交互，执行任务查询、状态更新等操作
Web应用：基于现代前端框架（如React）构建的浏览器应用，提供看板式任务管理界面

两者协同工作：浏览器中的Web应用通过API与服务端通信，实现数据存取

为何选择Web界面？

可视化任务管理是核心价值。相较于CLI的文本列表（backlog task list），Web界面提供：

项目进度全景概览
拖拽式状态变更
表单化任务详情编辑
团队协作场景适配

特别适用于项目规划、每日站会等需要图形化管理的场景。

启动Web界面

通过CLI命令即可启动：

backlog browser

执行流程：

本地启动Web服务端（默认端口6420）
自动打开浏览器访问http://localhost:6420
展示项目任务看板

终端输出

在这里插入图片描述

停止服务使用Ctrl + C（macOS为Cmd + C）。

网页测试：

在这里插入图片描述

技术实现解析

Web界面运行机制包含两大关键流程：

数据加载

在这里插入图片描述

状态更新

在这里插入图片描述

核心通信基于RESTful API设计，服务端与核心协调器交互，通过文件系统操作实现数据持久化。

RESTful API是一种基于HTTP协议的设计风格，通过URL定位资源，用GET、POST等标准方法操作数据，返回JSON/XML格式结果，简洁易扩展。

核心代码

浏览器端API客户端

// src/web/lib/api.ts（简化片段）
export class ApiClient {
    // 获取全部任务
    async fetchTasks(): Promise<Task[]> {
        const response = await fetch(`${API_BASE}/tasks`);
        return response.json(); 
    }

    // 更新任务状态
    async updateTask(id: string, updates: Partial<Task>): Promise<Task> {
        const response = await fetch(`${API_BASE}/tasks/${id}`, {
            method: "PUT",
            headers: {"Content-Type": "application/json"},
            body: JSON.stringify(updates)
        });
        return response.json();
    }
}

服务端请求处理

// src/server/index.ts（简化片段）
export class BacklogServer {
    private async handleApiRequest(req: Request): Promise<Response> {
        // 处理任务获取请求
        if (pathname === "/api/tasks" && method === "GET") {
            const tasks = await this.core.filesystem.listTasks();
            return Response.json(tasks);
        }

        // 处理任务更新请求
        if (taskIdMatch && method === "PUT") {
            const taskId = taskIdMatch[1];
            const updates = await req.json();
            await this.core.updateTask(updatedTask, false);
            return Response.json(updatedTask);
        }
    }
}

界面对比指南

特性维度	CLI	Web界面
交互方式	命令行输入	图形化点击/拖拽
执行速度	适用于快速脚本操作	侧重可视化编辑效率
适用场景	批量创建/自动化任务	任务状态管理/团队协作
显示方式	终端文本输出	浏览器看板视图
访问途径	终端设备	支持多端浏览器访问

总结

本章介绍了Backlog.md的Web界面架构及其与服务端的协作机制，核心要点包括：

双模块架构：服务端（数据处理） + Web应用（界面呈现）
API驱动的通信模式
与核心协调器的深度集成
可视化看板的实现原理

我们已掌握：

Web界面的启动与基本操作
服务端请求处理流程
浏览器端与服务端的通信机制
CLI与Web界面的场景适配策略

下一章将探索Backlog.md与版本控制系统的深度集成——Git操作！

Git操作

补充：

CI/CD

CI/CD 是 持续集成（Continuous Integration）和 持续交付（Continuous Delivery）或 持续部署（Continuous Deployment）的缩写。它是现代软件开发中一种重要的实践方法，旨在通过自动化流程，加快软件的构建、测试和发布速度，同时提高软件质量和可靠性。

一、CI/CD 的含义

1. CI：持续集成（Continuous Integration）

定义：开发人员频繁地（每天多次）将代码变更合并到共享的主干（如 main 或 master 分支）。
关键动作：每次提交代码后，系统自动触发：
- 代码编译
- 运行单元测试、集成测试
- 代码质量检查（如 Lint、SonarQube）
目的：尽早发现集成错误，避免“集成地狱”。

2. CD：持续交付 / 持续部署（Continuous Delivery / Deployment）

持续交付（Continuous Delivery）：
- 确保代码始终处于可发布状态。
- 可以通过手动点击一键发布到生产环境。
持续部署（Continuous Deployment）：
- 比持续交付更进一步，自动将通过测试的代码部署到生产环境，无需人工干预。

✅ 简单理解：

CI = 自动化测试 + 代码集成
CD（交付） = 准备好发布，人工决定何时上线
CD（部署） = 完全自动化，测试通过就上线

二、举个例子 🌰

假设你和团队在开发一个电商网站，比如“每日优鲜”。

场景：你修改了“下单”功能

传统方式（无 CI/CD）：

你写完代码，发给测试人员。
测试人员手动部署到测试环境。
发现 bug，你修改，再提交……反复沟通。
上线前，运维手动打包、部署，容易出错，耗时长。

使用 CI/CD 后：

你写完代码，提交到 Git（如 GitHub/GitLab）。
CI 触发：
- 自动拉取最新代码
- 编译项目
- 运行 500 个自动化测试
- 检查代码风格
- ✅ 全部通过 → 进入下一步
CD 触发：
- 自动部署到测试环境或预发布环境
- 测试团队验证
- 验证通过后：
  - 持续交付：项目经理点击“上线”按钮，自动部署到生产
  - 持续部署：系统自动上线，无需人工干预

🚀 结果：从提交代码到上线，可能只需 10 分钟，而不是 1 天。

三、常见的 CI/CD 工具

工具	说明
`GitHub Actions`	GitHub 自带的 CI/CD 工具，易用
`GitLab CI/CD`	GitLab 内置，`配置灵活`
Jenkins	老牌开源工具，插件丰富，适合`复杂`场景
`CircleCI`	`云端 CI/CD`，速度快
`Argo CD`	用于 `Kubernetes` 的持续部署工具