内容
# IssueDeck
English | [简体中文](README.zh-CN.md)
[](https://github.com/xq520mmy/IssueDeck/actions/workflows/ci.yml)
[](https://github.com/xq520mmy/IssueDeck/releases)
[](LICENSE)
<p align="center">
<img src="docs/assets/issuedeck-social-preview.png" alt="IssueDeck: a local-first issue deck for humans and AI coding agents" width="100%">
</p>
**比 Jira 更轻量，比 Markdown 更稳定**
IssueDeck 是一个本地优先、自托管的问题跟踪系统，适用于小型团队和 AI 编程工作流。它为多个项目提供了一个共享的 FastAPI + SQLite 跟踪器、一个面向人类的网页仪表盘和面向编程代理的 MCP 工具。
## 30 秒试用
使用最新的 PyPI 版本，并带有假演示数据：
```bash
uvx issuedeck demo --open
```
不需要克隆或实际项目数据。演示会创建一个本地的 `example` 项目，并打开仪表盘。使用 `issuedeck-local-token` 登录。
要尝试最新的未发布 `main` 分支：
```bash
uvx --from git+https://github.com/xq520mmy/IssueDeck issuedeck demo --open
```
## 为什么使用 IssueDeck
- 用一个结构化的、接近代码、提交、分支和发布的单一事实来源，取代特定于项目的 Markdown 跟踪器。
- 为人类和编程代理提供相同的工作流，而不是在仪表盘中维护一个地方，在另一个地方维护代理指令。
- 使用演示数据安全地开始，然后在准备好时添加实际项目配置。
查看 [截图画廊](docs/gallery.md) 以获取列表、看板、详情、搜索和项目创建界面。
日常检查快捷键在 [键盘快捷键](docs/keyboard-shortcuts.md) 中有文档记录。
代理交接和进度跟踪在 [代理工作会话](docs/agent-work-sessions.md) 中涵盖。
GitHub 积压导入在 [GitHub 问题导入](docs/github-issues-import.md) 中涵盖。
仪表盘 CSV、JSON 和 Markdown 上传在 [仪表盘文件导入](docs/dashboard-file-imports.md) 中涵盖。
重新打开早期的导入批次在 [仪表盘导入历史](docs/dashboard-import-history.md) 中涵盖。
导入后批量清理在 [仪表盘批量检查](docs/dashboard-bulk-triage.md) 中涵盖。
新工作空间的启动配置在 [项目模板](docs/project-templates.md) 中涵盖。
项目特定的元数据在 [自定义字段](docs/custom-fields.md) 中涵盖。
项目快照在 [审计包](docs/audit-bundles.md) 中涵盖。
## 功能
- 代理就绪：MCP 工具允许编程代理创建、更新、过滤、关联和交付跟踪工作，包括自定义字段，而无需爬取 Markdown。
- 代理工作会话跟踪代理正在处理哪个项目、目标、进度更新和最终结果。
- 多项目：一个 SQLite 数据库保存任意数量的项目，按 `project_key` 索引。每个项目都有自己的 `kinds`、`statuses`、`branches` 和数字 ID 前缀（例如 `FEAT-0001`、`BUG-0003`）。
- 项目定义的自定义字段，用于额外的项目元数据，例如优先级、估计、客户影响和源 URL，带有列表摘要、精确/范围/存在仪表盘和 API 过滤、批量更新和 CSV/JSON 导入映射。
- 启动项目模板和仪表盘/CLI 安装的本地模板包示例，用于支持队列、内容日历和研究工作流。
- 通过 SQLite FTS5 进行全文搜索。
- 双向关系（`blocks`/`blocked_by`、`related_to`）。
- GitHub 问题、拉取请求、提交和其他审查上下文的外部链接。
- GitHub URL 助手，根据问题、拉取请求或提交 URL 创建链接的 IssueDeck 项目，无需完整的同步引擎。
- GitHub 问题导入器，用于将存储库问题从仪表盘或 CLI 拉入 IssueDeck，带有状态/标签过滤器和重复跳过。
- CSV、JSON 和 Markdown 任务列表导入从仪表盘或 CLI，用于将跟踪器导出、`TODO.md` 和 GitHub 检查清单项转换为 IssueDeck 工作项。
- 带有自动生命周期事件和手动评论的项目活动时间线。
- 创建、更新、交付、删除和恢复事件的签名生命周期 Webhook，用于下游自动化。
- 团队可见的项目更新的 Slack、Discord 和电子邮件生命周期通知。
- 用于积压、活动、阻塞、准备交付、完成、删除和最近触摸项目的内置仪表盘工作队列。
- 仪表盘批量检查，用于更新状态、类型、标签、分支、删除和恢复多个选定项目。
- 仪表盘导入历史，用于重新打开最近的 GitHub、CSV、JSON 和 Markdown 导入批次。
- 项目范围的已保存仪表盘过滤器，用于可重用的视图，例如活动错误、阻塞工作、发布队列和特定于标签的搜索。
- 软删除 + 恢复。
- 带有版本 + 提交的可交付记录，按交付分支查询。
- Markdown 导出（每个项目一个文件）和变更日志渲染。
- 项目级审计包，用于配置、项目、关系、工作会话和导入历史的 ZIP 快照。
- 从现有 Markdown 跟踪器进行 Frontmatter 迁移。
- 服务器渲染的仪表盘，带有列表、看板、详情、搜索和创建/编辑流程。
- 仪表盘检查的键盘友好，适用于搜索、过滤、创建和项目关注。
- 带有启动模板、语言切换和首次运行设置检查清单的仪表盘项目创建。
- 用于编程代理工作流的 MCP 工具。
## 要求
- Python 3.11+
- [uv](https://docs.astral.sh/uv/)
- Docker，可选用于容器部署
- Node.js 20+，仅在更改仪表盘样式时需要
## 快速入门
在不克隆的情况下尝试最新的 PyPI 版本：
```bash
uvx issuedeck demo --open
```
要尝试 GitHub 上未发布的更改：
```bash
uvx --from git+https://github.com/xq520mmy/IssueDeck issuedeck demo --open
```
使用假演示数据启动本地仪表盘：
```bash
uv run issuedeck demo
```
这会在没有 `server.toml` 的情况下创建本地 `server.toml`，应用数据库迁移，用假项目填充 `example` 项目，并启动服务器。然后打开 `http://127.0.0.1:8765/dashboard/example`，使用 `issuedeck-local-token` 登录。
要自动打开仪表盘：
```bash
uv run issuedeck demo --open
```
健康端点：
```bash
curl http://127.0.0.1:8765/healthz
curl http://127.0.0.1:8765/readyz
```
如果第一次运行失败，可能是由于缺少 `uv`、端口被占用、令牌问题、SQLite 迁移或 Docker Compose 启动，参见 [首次运行故障排除指南](docs/troubleshooting.md)。
仪表盘 CSS 已在存储库中提交，因此不需要 Node 即可运行 IssueDeck。如果更改仪表盘模板、帮助类映射或 `tailwind.config.cjs`，请使用 `npm ci && npm run build:css` 重建 CSS。
## 配置
`server.toml` 控制服务器：
```toml
host = "0.0.0.0"
port = 8765
api_token = "change-me-in-production"
data_dir = "./data"
projects_dir = "./projects"
```
在生产环境中，请通过环境变量设置令牌，而不是提交：
```bash
export ISSUEDECK_API_TOKEN="your-secret-token"
```
PowerShell：
```powershell
$env:ISSUEDECK_API_TOKEN = "your-secret-token"
```
`api_token` 仍然是向后兼容的管理令牌。对于多个客户端，请添加作用域令牌：
```toml
[[tokens]]
name = "readonly"
token = "replace-with-readonly-token"
scopes = ["read"]
[[tokens]]
name = "agent"
token = "replace-with-agent-token"
scopes = ["agent"]
[[tokens]]
name = "admin-dashboard"
token = "replace-with-admin-token"
scopes = ["admin"]
```
`read` 令牌可以调用只读 API 端点。`agent` 令牌可以读写 REST API 资源，用于 MCP/编程代理工作流。`admin` 令牌具有完全的 API 访问权限，可以登录仪表盘。
项目配置存储在 `projects/*.toml` 中。仪表盘可以从基本问题跟踪器、代理工作流和软件团队启动模板创建新项目；直接编辑 TOML 以进行高级自定义。本地模板包可以通过 `project_templates_dir` 添加；参见 [项目模板](docs/project-templates.md)。
相同的启动模板和可安装的示例包可从 CLI 获得：
```bash
uv run issuedeck list-project-templates --config server.toml
uv run issuedeck list-project-template-examples
uv run issuedeck install-project-template-example support --config server.toml
uv run issuedeck export-project-template myapp --config server.toml
uv run issuedeck create-project myapp \
--config server.toml \
--name "My App" \
--template agent
```
可选的签名生命周期 Webhook 可以在项目创建、更新、交付、删除或恢复时通知下游自动化；参见 [生命周期 Webhook](docs/webhooks.md)。同一指南涵盖 Slack、Discord 和电子邮件团队通知。FastAPI、Flask 和 Node/Express 的接收器示例位于 [Webhook 接收器示例](docs/webhook-receivers.md)。
项目文件存储在 `projects/*.toml` 中。每个文件定义一个项目，必须使用相同的 file stem、`key` 和仪表盘 URL 段。存储库包含 `projects/example.toml`，因此快速入门立即生效：
```toml
key = "myproject"
name = "My Project"
```
仪表盘：`http://127.0.0.1:8765/dashboard/myproject`
## 演示数据
使用假数据进行截图、文档或干净的本地演示：
```bash
uv run issuedeck seed-demo --config server.toml --project-key example
```
如果目标项目已经有项目，命令会拒绝覆盖它。要故意替换该项目的项目，请添加 `--force-reset`。
对于完整的首次运行流程，请使用 `uv run issuedeck demo`；它会创建配置、运行迁移、填充假数据并启动仪表盘。
## CLI 项目工作流
在不启动仪表盘的情况下创建本地项目：
```bash
uv run issuedeck create-item \
--config server.toml \
--project-key example \
--kind feature \
--title "Add release checklist" \
--tag ops \
--custom-field priority=high \
--external-link "Spec | https://example.com/spec"
```
使用 `--body` 表示短注释，使用 `--body-file notes.md` 表示较长的 Markdown，使用 `--dry-run` 预览写入前的有效载体。
更新同一终端流程中的现有项目：
```bash
uv run issuedeck update-item FEAT-0001 \
--config server.toml \
--project-key example \
--status in_progress \
--append-body-file notes.md \
--custom-field estimate=5
```
`update-item` 可以替换标题、状态、正文、标签、分支、自定义字段和外部链接。使用 `--clear-external-links` 删除链接集。
用于导入后清理，批量更新多个项目：
```bash
uv run issuedeck bulk-update-items FEAT-0001 FEAT-0002 \
--config server.toml \
--project-key example \
--status in_progress \
--tag triaged \
--tag-mode replace
```
设置 `--action delete` 或 `--action restore` 进行批量清理。批量更新还支持分支和自定义字段更改。
记录已交付的版本和提交列表：
```bash
uv run issuedeck ship-item FEAT-0001 \
--config server.toml \
--project-key example \
--branch main \
--version v1.0.0 \
--commit abc1234
```
追加注释、验证注释或交接事件：
```bash
uv run issuedeck append-item-event FEAT-0001 \
--config server.toml \
--project-key example \
--event-type verification \
--actor-type agent \
--actor-name codex \
--body "Checked locally before release."
```
在不启动仪表盘的情况下列出本地项目：
```bash
uv run issuedeck list-items \
--config server.toml \
--project-key example \
--status in_progress \
--custom-field 'estimate>=3'
```
使用 `--format json` 表示脚本。过滤器包括 `--kind`、`--status`、`--tag`、`--applies-to`、`--relation-type`、`--custom-field`、`--include-deleted` 和 `--only-deleted`。
显示具有完整详细信息的单个项目：
```bash
uv run issuedeck get-item FEAT-0001 --config server.toml --project-key example
```
## GitHub URL 助手
从 GitHub 问题、拉取请求或提交 URL 创建 IssueDeck 项目：
```bash
uv run issuedeck import-github-url \
--config server.toml \
--project-key example \
--kind feature \
https://github.com/example/repo/issues/42
```
使用 `--dry-run` 预览创建有效载体后再写入。参见 [GitHub URL 导入](docs/github-import.md)。
## GitHub 问题导入
导入存储库的开放问题，并安全地重新运行而不会重复导入已经具有相同 GitHub 外部链接的项目：
```bash
uv run issuedeck import-github-issues example/repo \
--config server.toml \
--project-key example \
--kind feature \
--state all \
--status-map closed=done
```
使用 `GITHUB_TOKEN` 或 `--github-token` 表示私有存储库或更高的速率限制。从仪表盘打开一个项目，并在侧边栏中选择 **导入 GitHub**，以在写入前预览相同的导入。参见 [GitHub 问题导入](docs/github-issues-import.md)。
## Markdown 任务列表导入
从文件或目录导入普通的 Markdown 检查清单：
```bash
uv run issuedeck import-markdown-list TODO.md \
--config server.toml \
--project-key example \
--kind feature \
--tag planning
```
已检查的任务默认被跳过；添加 `--include-checked` 将它们导入到第一个终端项目状态。参见 [Markdown 任务列表导入](docs/markdown-task-list-import.md)。
## CSV 导入
导入跟踪器导出和电子表格行：
```bash
uv run issuedeck import-csv issues.csv \
--config server.toml \
--project-key example \
--preset github \
--status-map open=proposed \
--status-map closed=done
```
使用 `--field-alias` 表示自定义标头，使用 `--dry-run` 在写入前进行验证。参见 [CSV 导入](docs/csv-import.md)。
## JSON 导入
导入 JSON 数组或包装的跟踪器导出，如 `{ "issues": [...] }`：
```bash
uv run issuedeck import-json issues.json \
--config server.toml \
--project-key example \
--preset github \
--status-map open=proposed \
--status-map closed=done
```
使用 `--field-alias` 表示自定义键，使用 `--dry-run` 在写入前进行验证。参见 [JSON 导入](docs/json-import.md)。
## 主机跟踪器导出
有关 GitHub 问题、Linear、Jira 和通用表格导出，请参见 [主机跟踪器导出帮助程序](docs/hosted-tracker-exports.md)。该指南显示源导出命令和匹配的 `import-json` / `import-csv` 调用。
## 运行服务器
```bash
# 启动服务器；它在监听之前会应用数据库迁移。
export ISSUEDECK_API_TOKEN="your-secret-token"
uv run issuedeck serve --config server.toml
```
PowerShell：
```powershell
$env:ISSUEDECK_API_TOKEN = "your-secret-token"
uv run issuedeck serve --config server.toml
```
仪表盘使用与 API 相同的共享令牌。打开仪表盘 URL，输入 `ISSUEDECK_API_TOKEN`，IssueDeck 将创建一个 HTTP 仅浏览器会话 cookie。API 和 MCP 客户端应继续使用 `Authorization: Bearer <token>` 头。
## Docker
默认的 Compose 文件从 GitHub 容器注册表拉取已发布的镜像：
```bash
cp server.toml.example server.toml
cp .env.example .env
docker compose pull
docker compose up -d
```
在 `.env` 中打开 `http://127.0.0.1:8765/dashboard/example` 并使用 `ISSUEDECK_API_TOKEN` 登录。
要运行本地构建的镜像：
```bash
docker build -t issuedeck:local .
ISSUEDECK_IMAGE=issuedeck:local docker compose up -d
```
有关离线或服务器部署的详细信息，请参见 [DEPLOY.md](DEPLOY.md)。中文部署指南可在 [docs/deployment.zh.md](docs/deployment.zh.md) 找到。对于小型生产强化检查清单，请参见 [Docker Compose 强化](docs/docker-compose-hardening.md)。
## MCP 标准输入/输出进程
有关客户端特定示例，请参见 [MCP 客户端设置](docs/mcp-clients.md)。
通用标准输入/输出配置：
```json
{
"mcpServers": {
"issuedeck": {
"command": "uv",
"args": ["run", "python", "-m", "issuedeck.mcp"],
"env": {
"ISSUEDECK_BASE_URL": "http://127.0.0.1:8755",
"ISSUEDECK_TOKEN": "your-secret-token"
}
}
}
}
```
> **注意：** MCP 客户端读取 `ISSUEDECK_TOKEN`；服务器读取 `ISSUEDECK_API_TOKEN`。它们可能具有相同的值，但变量名称因设计而不同（客户端/服务器是单独的进程）。
18 种工具：`list_projects`、`get_project_config`、`create_item`、`update_item`、`bulk_update_items`、`ship_item`、`append_item_event`、`delete_item`、`get_item`、`list_items`、`search_items`、`add_relationship`、`remove_relationship`、`start_work_session`、`list_work_sessions`、`get_work_session`、`update_work_session`、`finish_work_session`。`create_item` 和 `update_item` 接受 `custom_fields`；`bulk_update_items` 可以更新多个项目中的自定义字段；`list_items` 接受重复的 `custom_field` 过滤器。
MCP 进程读取 `ISSUEDECK_BASE_URL` 和 `ISSUEDECK_TOKEN`，然后通过 HTTP 与 REST 服务器通信。它不直接访问 SQLite。
## 从 Markdown Frontmatter 迁移
```bash
uv run issuedeck migrate \
--config server.toml \
--from-frontmatter /path/to/markdown-tracker \
--project-key myproject
```
添加 `--dry-run` 以预览而不写入。添加 `--force-reset` 以先清除现有项目。
导入程序接受规范模式以及常见的别名，如 `type`、`state` 和 `labels`；有关完整模式和自定义别名选项，请参见 [Markdown Frontmatter 导入](docs/markdown-frontmatter-import.md)。
## 导出
```bash
uv run issuedeck export \
--config server.toml \
--project-key myproject \
--out ./export
```
为每个项目写入一个带有 YAML Frontmatter 的 `.md` 文件。
## 开发
```bash
uv sync
uv run pytest
uv run ruff check .
```
对于仪表盘 UI 工作：
```bash
npm ci
npm run build:css
```
在打开拉取请求之前，请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。维护者和 AI 编程窗口交接规则在 [维护者工作流](docs/maintainer-workflow.md) 中有文档记录。仪表盘 UI 工作应遵循 [DESIGN.md](DESIGN.md)。使用 [仪表盘可访问性烟雾检查清单](docs/accessibility-checklist.md) 进行 UI 更改。请在 [ROADMAP.md](ROADMAP.md) 中查看计划工作和贡献领域。启动贡献候选人在 [启动问题积压](docs/launch-issues.md) 中。维护者启动副本收集在 [启动工具包](docs/launch-kit.md) 中。对于支持和问题报告指南，请参见 [SUPPORT.md](SUPPORT.md)。对于敏感漏洞，请遵循 [SECURITY.md](SECURITY.md)。有关 PyPI 受信任发布的设置，请参见 [docs/pypi-publishing.md](docs/pypi-publishing.md)。
## 许可证
MIT。参见 [LICENSE](LICENSE)。Vendored 仪表盘浏览器资产列在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器