AgentX

面向终端开发者的原生AI问题追踪器。

快速、键盘驱动的问题追踪，具有依赖图、TUI仪表盘和MCP服务器集成功能。

---

✨ 特性

🎯 核心问题管理

• 创建与追踪：带有状态、优先级、工作量估算、标签和依赖关系的问题
• 智能工作流：自动状态转换（待办事项 → 准备就绪 → 进行中 → 完成）
• 快速操作：批量操作、检查点、上下文切换
• 模糊搜索：通过部分ID、标题或标签查找问题

📊 可视化与分析

• TUI 仪表盘：全屏交互界面（类似Jira的统一列表）
• 依赖图：ASCII艺术形式的问题关系可视化
• 关键路径：在依赖链中找到瓶颈
• 指标：跟踪完成率、速度和燃尽图

🤖 AI 集成

• MCP 服务器：通过模型上下文协议暴露问题追踪器
• 代理友好：结构化数据、JSON输出、语义操作
• 上下文感知：专注于相关问题，显示被阻塞的内容

🔧 开发者体验

• Git 集成：自动检测分支上下文、提交引用
• 交互模式：复杂操作的引导向导
• Shell 补全：支持 Bash、Zsh、Fish
• 零配置：开箱即用，存储在 ~/.local/share/agentx

🎨 TUI 仪表盘

交互式仪表盘提供了类似Jira的终端体验：

功能

• ✅ 统一列表：所有问题在一个可滚动视图中
• ✅ 实时搜索：输入 / 并立即开始搜索
• ✅ 状态分隔符：清晰的状态视觉分隔
• ✅ 优先级图标：🔴 关键，🟡 高，🟢 中，⚪ 低
• ✅ 标签显示：内联查看所有标签
• ✅ 工作量估算：跟踪时间承诺
• ✅ Vim 键绑定：hjkl 导航 + 搜索

---

🚀 快速入门

安装

# 克隆并构建
git clone https://github.com/can1357/agentx.git
cd agentx
cargo build --release

# 安装到PATH
cargo install --path .

创建您的第一个问题

# 快速创建
agentx new "修复身份验证错误" -p 高 -e 2d -t bug -t security

# 交互模式
agentx new -i

启动 TUI 仪表盘

agentx ui
# 或使用别名：
agentx dash

导航：

• ↑↓ 或 jk - 导航问题
• / - 搜索（实时结果）
• g/G - 跳转到顶部/底部
• PgUp/PgDn - 快速滚动
• Tab - 切换窗格
• q - 退出

---

📖 命令参考

问题生命周期

# 创建新问题
agentx new "任务描述" [选项]
# 或使用别名：
agentx add "任务描述" [选项]
  -p, --priority <critical|high|medium|low>
  -e, --effort <持续时间>     # 例如："2d", "4h", "1w"
  -t, --tag <标签>             # 可以多次使用
  -d, --depends <ID>          # 添加依赖
  -i, --interactive           # 启动向导

# 更新状态
agentx start <ID>             # 标记为进行中
agentx block <ID> <原因>    # 标记为被阻塞
agentx close <ID>             # 标记为完成
agentx defer <ID>             # 移至待办事项
agentx activate <ID>          # 从待办事项激活

# 查看问题
agentx list                   # 所有开放问题
# 或使用别名：
agentx ls                     # 所有开放问题
agentx show <ID>              # 详细信息
agentx context                # 当前工作上下文
agentx focus                  # 最高优先级
agentx blocked                # 所有被阻塞的问题
agentx ready                  # 准备开始
agentx quick-wins             # 低工作量的任务

依赖关系

# 添加依赖
agentx depend add <ID> <依赖于>

# 删除依赖
agentx depend remove <ID> <依赖于>

# 可视化图
agentx deps-graph [ID]        # ASCII艺术
agentx dependencies <ID>      # 显示依赖项和依赖于

# 查找瓶颈
agentx critical-path          # 最长依赖链

标签与组织

# 添加标签
agentx tag add <ID> <标签>

# 删除标签
agentx tag remove <ID> <标签>

# 按标签列出（在列表命令中）
agentx list -t backend -t api

批量操作

# 启动多个问题
agentx bulk-start <ID1> <ID2> <ID3>

# 关闭多个问题
agentx bulk-close <ID1> <ID2> <ID3>

分析

# 显示指标
agentx metrics

# 最近更改
agentx summary

# 按状态统计问题数量
agentx list --json | jq '.[] | .metadata.status' | sort | uniq -c

---

🔌 MCP 服务器

AgentX 可以作为MCP服务器运行，用于AI助手集成：

# 在标准输入输出上启动服务器
agentx serve

可用工具

MCP服务器向AI助手暴露了这些操作：

工具	描述
create_issue	使用元数据创建新问题
list_issues	按状态/优先级/标签查询问题
update_issue	更改状态，添加标签，更新字段
show_issue	获取特定问题的详细信息
add_dependency	将问题链接在一起
get_blocked	查找所有被阻塞的问题
get_ready	查找准备开始的问题

示例 Claude Desktop 配置

{
  "mcpServers": {
    "agentx": {
      "command": "agentx",
      "args": ["serve"],
      "env": {}
    }
  }
}

---

🛠️ 高级用法

从 YAML 导入

# 批量导入问题
agentx import issues.yaml

格式：

issues:
  - title: "设置CI/CD管道"
    priority: 高
    effort: "1w"
    tags: ["devops", "基础设施"]
    depends_on: []
  - title: "编写集成测试"
    priority: 中
    effort: "3d"
    tags: ["测试"]
    depends_on: ["BUG-111"]

别名管理

# 为长ID创建短别名
agentx alias add auth BUG-123
agentx show auth              # 等同于：agentx show BUG-123

# 列出别名
agentx alias list

检查点

在单个问题中跟踪进度：

# 添加检查点
agentx checkpoint BUG-123 "完成数据库迁移"
agentx checkpoint BUG-123 "更新API端点"

# 查看问题详情
agentx show BUG-123

JSON 输出

所有命令都支持JSON输出，用于脚本：

# 获取JSON输出
agentx list --json | jq '.[] | select(.metadata.priority == "Critical")'

# 按状态统计问题数量
agentx list --json | jq 'group_by(.metadata.status) | map({status: .[0].metadata.status, count: length})'

---

📁 项目结构

agentx/
├── src/
│   ├── main.rs           # CLI入口点
│   ├── issue.rs          # 核心问题类型
│   ├── storage.rs        # 文件持久化
│   ├── commands/         # CLI命令
│   ├── tui/              # 仪表盘UI
│   │   ├── mod.rs        # 应用状态及事件循环
│   │   ├── widgets/      # 看板、图表、图形
│   │   └── views/        # 仪表盘布局
│   ├── mcp/              # MCP服务器
│   └── utils/            # 辅助工具
├── data/                 # 问题存储（自动生成）
├── Cargo.toml
└── README.md

数据位置： ~/.local/share/agentx/

---

🎯 工作流程示例

日常工作流程

# 上午：检查上下文
agentx focus                  # 今天重要的是什么？
agentx context                # 我正在做什么？

# 开始工作
agentx start BUG-123
agentx checkpoint BUG-123 "初步调查完成"

# 发现阻塞
agentx block BUG-123 "等待DB迁移批准"

# 切换到快速胜利
agentx quick-wins
agentx start DOC-45

# 结束一天
agentx close DOC-45
agentx summary                # 我完成了什么？

规划一个特性

# 创建特性分解
agentx new "API认证层" -p 高 -e 2w -t api
agentx new "添加JWT令牌生成" -p 高 -e 3d -t api -d FEA-100
agentx new "实现令牌刷新" -p 中 -e 2d -t api -d FEA-101
agentx new "添加速率限制" -p 低 -e 1d -t api -d FEA-101

# 可视化依赖关系
agentx deps-graph FEA-100

# 查找关键路径
agentx critical-path

Bug 诊断

# 从文件导入Bug
agentx import bugs.yaml

# 审查关键问题
agentx list -p critical

# 启动仪表盘进行诊断
agentx dash

# （在仪表盘中：使用 / 搜索，标记优先级）

---

🔧 配置

AgentX 使用合理的默认值，但可以进行定制：

# 初始化配置
agentx init

# 位置：~/.config/agentx/config.yaml

示例 config.yaml：

# 问题ID格式
id_prefix: "TASK"
id_start: 1

# 默认值
defaults:
  priority: 中
  effort: null
  tags: []

# TUI主题
theme:
  name: "default"

---

🧪 测试

# 运行测试
cargo test

# 带日志运行
RUST_LOG=debug agentx dash

# 检查性能
hyperfine 'agentx list'

---

📜 许可证

MIT 许可证 - 详情见 LICENSE 文件。