AI导哈

Markdown项目管理工具

AGINEAR是一款基于Markdown的项目管理工具，提供CLI、Web GUI和MCP服务器支持，适用于开发团队和AI编程代理的任务管理和路线图规划。

  • by Legorobotdude
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 Legorobotdude/AGINEAR

使用说明

老年人

Markdown原生项目管理。 todo.md 和 roadmap.md 是真理的唯一来源。CLI、Web GUI和MCP服务器——所有这些都由无损降价引擎提供支持。

快速开始

npx aginear init        # Creates todo.md, roadmap.md, .devplan/config.json
npx aginear list        # View tasks
npx aginear serve       # Launch web GUI at http://localhost:4040

设置

需要Node.js>=18。

cd your-repo
npx aginear init

这将创建：

your-repo/
├── todo.md                  # Your tasks (editable by hand or via CLI/GUI)
├── roadmap.md               # Your milestones
├── .devplan/
│   └── config.json          # Per-repo configuration
└── .gitignore               # .devplan/ entry appended automatically

这两个markdown文件都是您可以直接编辑的——AGINEAR保留了您添加的每一个字节的格式（空行、散文、注释）。

全局安装（可选）

npm install -g aginear

Markdown格式

todo.md

# My Project

## Backlog
- [ ] Set up database @aditya #backend !high ^2025-06-01
- [ ] Write API docs #docs

## In Progress
- [ ] Build auth flow @aditya #backend !critical
  - [x] Design token schema
  - [ ] Implement JWT validation
    - [ ] Add RS256 support
  - [ ] Write auth middleware
  Notes about the auth flow.

## Done
- [x] Initialize repo

章节 是 ## 标题——它们成为GUI中的看板列。

任务 是 - [ ] （不完整）或 - [x] （完整）列出项目。

子任务 在其父级下缩进2个空格。深度可达3层。

备注 在任务（不是列表项）下缩进纯文本。

内联元数据 可以出现在任务标题的任何位置：

标记 含义 示例
@name 受让人 @aditya
#tag 标签（允许多个） #backend #api
!priority 优先级 !critical, !high, !medium, !low
^YYYY-MM-DD 到期日 ^2025-06-01

路线图.md

# Product Roadmap

## MVP Launch
status: in-progress
progress: 60%

Core features for initial release.

- [x] User authentication
- [x] Basic CRUD
- [ ] Payment integration

## V2 Features
status: planned

- [ ] Analytics dashboard
- [ ] Export to CSV

里程碑 是 ## 标题。

元数据 是 key: value 标题下的行：

  • status: — planned, in-progress, completed, blocked
  • progress: — 0% 到 100%

描述 是元数据和任务项之间的任何散文文本。

CLI参考

任务管理

# List all tasks
aginear list
aginear list --section "In Progress"
aginear list --tag backend
aginear list --assignee aditya

# Add a task
aginear add "Implement search"
aginear add "Build dashboard" --section "In Progress" --assign aditya --priority high --tag frontend --tag ui --due 2025-06-01

# Mark complete / uncomplete
aginear done "search"              # Fuzzy matches title
aginear done 3                     # By displayed list number
aginear done 0e0023                # By ID prefix (shown in list output)

# Move between sections
aginear move "search" --to "In Progress"

# Edit properties
aginear edit "search" --title "New title" --assign bob --priority medium --due 2025-07-01

# Remove
aginear remove "search"

任务标识

所有需要 <query> argument使用此策略解决任务：

  1. 数值 --在显示的列表中按位置匹配(aginear done 3)
  2. 6-8个十六进制字符 --按任务ID前缀匹配(aginear done 0e0023)
  3. 否则 --任务标题上不区分大小写的子字符串匹配(aginear done "auth flow")

如果多个任务匹配，您将看到一个消歧列表。

路线图管理

# View roadmap
aginear roadmap

# Add milestone
aginear roadmap add "V3 Features" --status planned

# Update milestone
aginear roadmap update "MVP" --status completed --progress 100

Web图形用户界面

aginear serve              # http://localhost:4040
aginear serve --port 8080  # Custom port

特征：

  • 列间带有拖放功能的看板
  • 单击任何任务以编辑标题、受让人、优先级、标签、截止日期
  • 通过复选框切换任务完成
  • 带有进度条和状态徽章的路线图时间线视图
  • 当磁盘上的文件发生更改时，通过WebSocket进行实时更新

初始化

aginear init

创造 todo.md, roadmap.md，以及 .devplan/config.json 默认情况下。跳过任何已存在的文件。追加 .devplan/ 到 .gitignore.

MCP服务器

AGINEAR包括一个MCP服务器，因此AI编码代理（Claude Desktop、Cursor、Claude Code等）可以读取和修改您的项目任务。

Claude桌面设置

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "aginear": {
      "command": "npx",
      "args": ["aginear", "mcp"],
      "cwd": "/absolute/path/to/your/repo"
    }
  }
}

光标设置

添加到 .cursor/mcp.json 在您的项目中：

{
  "mcpServers": {
    "aginear": {
      "command": "npx",
      "args": ["aginear", "mcp", "--cwd", "."]
    }
  }
}

Claude代码的设置

添加到 .claude/settings.json 在您的项目中：

{
  "mcpServers": {
    "aginear": {
      "command": "npx",
      "args": ["aginear", "mcp", "--cwd", "."]
    }
  }
}

可用工具

工具 描述 输入
get_todos 获取所有任务，可选择过滤 { section?, tag?, assignee?, priority? }
add_task 添加新任务 { title, section?, assignee?, tags?, priority?, due? }
update_task 更新现有任务 { search, updates: { title?, assignee?, priority?, tags?, due?, completed? } }
move_task 将任务移动到其他部分 { search, to_section }
complete_task 将任务标记为已完成 { search }
remove_task 删除任务 { search }
get_roadmap 获取完整路线图 {}
update_milestone 更新里程碑状态/进度 { search, status?, progress? }

这 search 参数通过ID前缀或不区分大小写的标题子字符串进行匹配。

配置

.devplan/config.json 是可选的。如果缺少，AGINEAR将使用合理的默认值。

{
  "files": {
    "todo": "./todo.md",
    "roadmap": "./roadmap.md"
  },
  "gui": {
    "port": 4040
  },
  "columns": ["Backlog", "In Progress", "Review", "Done"],
  "tags": {}
}
密钥 默认值 描述
files.todo ./todo.md todo文件的路径（相对于配置目录）
files.roadmap ./roadmap.md 路线图文件的路径（相对于配置目录）
gui.port 4040 web GUI的端口
columns ["Backlog", "In Progress", "Review", "Done"] 看板列名
tags {} 标签名到十六进制颜色映射

从以下位置向上走即可解决配置问题 cwd 寻找 .devplan/config.json （比如 .git).配置中的文件路径是相对于包含以下内容的目录解析的 .devplan/.

REST API

跑步时 aginear serve，这些端点可用：

待办事项

方法 端点 主体 描述
GET /api/todos -- JSON格式的完整todo文档
POST /api/todos/tasks { title, section?, assignee?, tags?, priority?, due? } 添加任务
PATCH /api/todos/tasks/:id { title?, assignee?, tags?, priority?, dueDate?, completed? } 更新任务
DELETE /api/todos/tasks/:id -- 删除任务
POST /api/todos/tasks/:id/move { section, position? } 移动任务
POST /api/todos/tasks/:id/complete -- 切换完成

路线图

方法 端点 主体 描述
GET /api/roadmap -- JSON格式的完整路线图文档
PATCH /api/roadmap/milestones/:id { status?, progress? } 更新里程碑

双向通信

连接到 ws://localhost:4040 （同一端口）。当磁盘上的文件发生更改时，服务器会广播这些消息：

{ "type": "todos_updated", "data": { "title": "...", "sections": [...] } }
{ "type": "roadmap_updated", "data": { "title": "...", "milestones": [...] } }

发展

git clone https://github.com/Legorobotdude/AGINEAR.git
cd AGINEAR
pnpm install
pnpm -r build
pnpm -r test       # 89 tests across core + mcp

项目结构

packages/
  core/     # Shared CST parser, mutator, serializer (lossless round-tripping)
  cli/      # CLI commands (commander + chalk)
  mcp/      # MCP server (@modelcontextprotocol/sdk, stdio transport)
  web/      # Express server + React SPA (Vite + Tailwind + @dnd-kit)

发布新版本

  1. 在两个地方碰撞版本：

    • publish-package.json --the "version" 字段（这是npm看到的）
    • packages/cli/src/index.ts --the .version() 呼叫指挥官（这就是 aginear --version 打印）

  2. 构建、打包和验证：

    pnpm run publish:build
pnpm run publish:pack       # creates aginear-<version>.tgz in repo root

  3. 发布：

    cd dist && npm publish --access public

这 publish:build 脚本执行以下操作：

  • 构建所有工作空间包(pnpm -r build)
  • 捆绑包 cli, mcp，以及 server 进入点 dist/ 通过tsup，内联 @devplan/* 工作区deps，同时将第三方deps保持在外部
  • 复制web客户端资产， publish-package.jsonREADME和许可证 dist/
  • 将节点设置为 dist/cli.js

关键设计决策

  • 无降价AST库 --自定义逐行CST解析器，保留每个字节。 serialize(parse(input)) === input.
  • markdown文件外没有状态 --The .md 文件就是数据库。配置仅用于首选项。
  • 微型安装 --所有内容都通过tsup/Vite打包成约94 KB（gzip压缩），并由npm安装第三方deps。

许可证

麻省理工学院

相关 MCP