内容
# AGINEAR
Markdown 原生项目管理。`todo.md` 和 `roadmap.md` 是唯一的真实来源。CLI、Web GUI 和 MCP 服务器 — 所有这些都由无损 Markdown 引擎驱动。
## 快速开始
```bash
npx aginear init # 创建 todo.md、roadmap.md、.devplan/config.json
npx aginear list # 查看任务
npx aginear serve # 在 http://localhost:4040 启动 Web GUI
```
## 设置
需要 Node.js >= 18。
```bash
cd your-repo
npx aginear init
```
这会创建：
```
your-repo/
├── todo.md # 您的任务（可手动或通过 CLI/GUI 编辑）
├── roadmap.md # 您的里程碑
├── .devplan/
│ └── config.json # 每个仓库的配置
└── .gitignore # .devplan/ 条目自动追加
```
两个 Markdown 文件都可以直接编辑 — AGINEAR 保留您添加的每个字节的格式（空行、散文、注释）。
### 全局安装（可选）
```bash
npm install -g aginear
```
---
## Markdown 格式
### todo.md
```markdown
# 我的项目
## 待办事项
- [ ] 设置数据库 @aditya #后端 !高优先级 ^2025-06-01
- [ ] 编写 API 文档 #文档
## 进行中
- [ ] 构建身份验证流程 @aditya #后端 !关键
- [x] 设计令牌模式
- [ ] 实现 JWT 验证
- [ ] 添加 RS256 支持
- [ ] 编写身份验证中间件
验证流程的说明。
## 已完成
- [x] 初始化仓库
```
**部分** 是 `##` 章节标题 — 它们在 GUI 中成为看板列。
**任务** 是 `- [ ]` （未完成）或 `- [x]` （已完成）列表项。
**子任务** 在其父任务下缩进 2 个空格。最多可达 3 级。
**备注** 是任务下的缩进纯文本（不是列表项）。
**内联元数据** 可以出现在任务标题的任何位置：
| 代币 | 含义 | 示例 |
|---|---|---|
| `@名称` | 指派人 | `@aditya` |
| `#标签` | 标签（允许多个） | `#后端 #api` |
| `!优先级` | 优先级 | `!关键`, `!高`, `!中等`, `!低` |
| `^YYYY-MM-DD` | 到期日 | `^2025-06-01` |
### roadmap.md
```markdown
# 产品路线图
## 最小可行产品（MVP）发布
状态：进行中
进度：60%
初始发布的核心功能。
- [x] 用户身份验证
- [x] 基本 CRUD
- [ ] 支付集成
## V2 功能
状态：计划中
- [ ] 分析仪表盘
- [ ] 导出为 CSV
```
**里程碑** 是 `##` 章节标题。
**元数据** 是标题下直接的 `键: 值` 行：
- `状态：` — `计划中`, `进行中`, `已完成`, `已阻塞`
- `进度：` — `0%` 至 `100%`
**描述** 是元数据和任务项之间的任何文本。
---
## CLI 参考
### 任务管理
```bash
# 列出所有任务
aginear list
aginear list --section "进行中"
aginear list --tag 后端
aginear list --assignee aditya
# 添加任务
aginear add "实现搜索"
aginear add "构建仪表盘" --section "进行中" --assign aditya --priority 高优先级 --tag 前端 --tag ui --due 2025-06-01
# 标记完成/未完成
aginear done "搜索" # 模糊匹配标题
aginear done 3 # 按显示列表编号
aginear done 0e0023 # 按 ID 前缀（在列表输出中显示）
# 移动到不同部分
aginear move "搜索" --to "进行中"
# 编辑属性
aginear edit "搜索" --title "新标题" --assign bob --priority 中等优先级 --due 2025-07-01
# 删除
aginear remove "搜索"
```
### 任务识别
所有需要 `<查询>` 参数的命令都使用以下策略解析任务：
1. **数字** — 按显示列表中的位置匹配（`aginear done 3`）
2. **6-8 个十六进制字符** — 按任务 ID 前缀匹配（`aginear done 0e0023`）
3. **否则** — 对任务标题进行不区分大小写的子字符串匹配（`aginear done "身份验证流程"`）
如果多个任务匹配，您将看到一个消歧列表。
### 路线图管理
```bash
# 查看路线图
aginear roadmap
# 添加里程碑
aginear roadmap add "V3 功能" --status 计划中
# 更新里程碑
aginear roadmap update "MVP" --status 已完成 --progress 100
```
### Web GUI
```bash
aginear serve # http://localhost:4040
aginear serve --port 8080 # 自定义端口
```
功能：
- 带有拖放功能的看板板，可在列之间移动
- 点击任何任务以编辑标题、指派人、优先级、标签、截止日期
- 通过复选框切换任务完成状态
- 带有进度条和状态徽章的路线图时间线视图
- 当磁盘上的文件更改时，通过 WebSocket 进行实时更新
### 初始化
```bash
aginear init
```
创建 `todo.md`, `roadmap.md`, 和 `.devplan/config.json`，并使用默认值。跳过已存在的任何文件。在 `.gitignore` 中追加 `.devplan/`。
---
## MCP 服务器
AGINEAR 包含一个 MCP 服务器，以便 AI 编码代理（Claude Desktop, Cursor, Claude Code 等）可以读取和修改您的项目任务。
### 为 Claude Desktop 设置
将以下内容添加到您的 Claude Desktop 配置文件（`~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"aginear": {
"command": "npx",
"args": ["aginear", "mcp"],
"cwd": "/绝对路径/到/您的/仓库"
}
}
}
```
### 为 Cursor 设置
在您的项目中将以下内容添加到 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"aginear": {
"command": "npx",
"args": ["aginear", "mcp", "--cwd", "."],
"cwd": "/绝对路径/到/您的/仓库"
}
}
}
```
### 为 Claude Code 设置
在您的项目中将以下内容添加到 `.claude/settings.json`：
```json
{
"mcpServers": {
"aginear": {
"command": "npx",
"args": ["aginear", "mcp", "--cwd", "."],
"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 会使用合理的默认值。
```json
{
"files": {
"todo": "./todo.md",
"roadmap": "./roadmap.md"
},
"gui": {
"port": 4040
},
"columns": ["待办事项", "进行中", "评审", "完成"],
"tags": {}
}
```
| 键 | 默认值 | 描述 |
|---|---|---|
| `files.todo` | `./todo.md` | 待办事项文件路径（相对于配置目录） |
| `files.roadmap` | `./roadmap.md` | 路线图文件路径（相对于配置目录） |
| `gui.port` | `4040` | Web GUI 端口 |
| `columns` | `["待办事项", "进行中", "评审", "完成"]` | 看板列名称 |
| `tags` | `{}` | 标签名称到十六进制颜色的映射 |
配置通过从 `cwd` 向上查找 `.devplan/config.json`（类似于 `.git`）来解析。配置文件中的路径相对于包含 `.devplan/` 的目录。
---
## REST API
运行 `aginear serve` 时，可使用以下端点：
### 待办事项
| 方法 | 端点 | 正文 | 描述 |
|---|---|---|---|
| `GET` | `/api/todos` | - | 完整的待办事项文档，格式为 JSON |
| `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? }` | 更新里程碑 |
### WebSocket
连接到 `ws://localhost:4040`（同一端口）。当磁盘上的文件更改时，服务器会广播以下消息：
```json
{ "type": "todos_updated", "data": { "title": "...", "sections": [...] } }
{ "type": "roadmap_updated", "data": { "title": "...", "milestones": [...] } }
```
---
## 开发
```bash
git clone https://github.com/Legorobotdude/AGINEAR.git
cd AGINEAR
pnpm install
pnpm -r build
pnpm -r test # 89 个测试，涵盖核心 + MCP
```
### 项目结构
```
packages/
core/ # 共享 CST 解析器、变更器、序列化器（无损循环）
cli/ # CLI 命令（commander + chalk）
mcp/ # MCP 服务器（@modelcontextprotocol/sdk，stdio 传输）
web/ # Express 服务器 + React SPA（Vite + Tailwind + @dnd-kit）
```
### 发布新版本
1. 在两个地方更新版本号：
- `publish-package.json` — `version` 字段（npm 看到的版本号）
- `packages/cli/src/index.ts` — Commander 中的 `.version()` 调用（`aginear --version` 打印的版本号）
2. 构建、打包并验证：
```bash
pnpm run publish:build
pnpm run publish:pack # 在仓库根目录创建 aginear-<version>.tgz
```
3. 发布：
```bash
cd dist && npm publish --access public
```
`publish:build` 脚本执行以下操作：
- 构建所有工作区包（`pnpm -r build`）
- 通过 tsup 将 `cli`, `mcp`, 和 `server` 入口点打包到 `dist/`，内联 `@devplan/*` 工作区依赖，同时保持第三方依赖外部
- 将 Web 客户端资产、`publish-package.json`、README 和 LICENSE 复制到 `dist/`
- 在 `dist/cli.js` 前添加 Node shebang
### 关键设计决策
- **没有 Markdown AST 库** — 自定义逐行 CST 解析器，保留每个字节。`serialize(parse(input)) === input`。
- **没有状态到处都是** — `.md` 文件是数据库。配置仅用于偏好设置。
- **小型安装** — 所有内容打包到 ~94 KB（gzip）通过 tsup/Vite，第三方依赖由 npm 安装。
## 许可证
MIT
