thask

---

使用 Thask 前后对比

	不使用 Thask	使用 Thask
你的要求	“重构这个支付函数。”	“重构这个支付函数。”
Agent 看到的内容	只有打开的文件。	文件，以及关系图中所有 depends_on 依赖该文件的节点。
Agent 的回答	看似合理的代码。三个下游流程悄然失效。	“这项更改会影响 3 个流程和 2 个 UI——我会一并更新，或者停下来询问。”
描述偏移	Agent 凭信心改写“原因”说明，你读过后，下一个 Agent 就把它当作事实依据。	Agent 默认阻止语义写入。它们会将提议提交到队列，由人工批准。事实来源仍由人掌控。

每项更改都会记录 6 个维度的来源信息（操作者、渠道、Agent 模型、变更类型、触发条件、证据），让下一个 Agent 知道哪些内容值得信任，哪些需要从代码中重新推导。

---

为什么选择 Thask？

电子表格会丢失上下文。线性问题跟踪器会隐藏关联。Thask 将你的产品映射为一个持续演进的图谱——让你能在问题发生前看到哪些地方会出问题。

原生支持 AI 通过 thask mcp serve 发布——Claude Code 和 Cursor 可将依赖关系图作为工具读取。询问“如果我更改这个，会影响什么？”即可获得切实的答案。

以图为先的思维方式 每个流程、任务和 Bug 都是一个节点。每个依赖关系都是一条可见的边。不再有隐藏的关联。

影响一目了然 只需点击一次，即可查看近期更改影响了哪些节点。在回归问题发布前将其捕获。

可自托管 docker compose up——就这么简单。你的数据保留在自己的基础设施中，不会被供应商锁定。

---

功能

交互式图编辑器

通过拖放操作管理 11 种类型的节点——Flow、Branch、Task、Bug、API、UI、Group，以及 v0.6.0 Knowledge OS 实体 Requirement、Decision、Experiment 和 Person。悬停并拖动边缘手柄即可连接节点。使用 fCOSE 力导向算法自动布局。

QA 影响模式

切换影响模式，即可立即突出显示已更改的节点及其下游依赖项。变暗的节点不受影响；发光的节点需要关注。

分组节点

将相关节点整理到可折叠的分组中。可将节点拖入或拖出分组。可自由调整分组大小。双击即可折叠，并显示子节点数量徽标。

状态跟踪与筛选

使用颜色编码的视觉效果，将每个节点标记为 PASS / FAIL / IN_PROGRESS / BLOCKED。按节点类型或状态筛选图谱，聚焦重要内容。

节点详情面板

可滑出的完整编辑面板——包括标题、描述（支持 Markdown 渲染）、类型、状态、标签、关联节点，以及完整的更改历史审计日志。

边关系

14 种具有不同颜色的边类型：基础 5 种（depends_on、blocks、related、parent_child、triggers）以及 v0.6.0 Knowledge OS 动词（realizes、conflicts、drives、supersedes、tests、produced、owns、decided、reported）。每条边还包含一个 JSONB metadata 字段——supersedes 记录 {reason}，produced 记录 {outcome_summary} 等。可拖动路径点来调整边的走向。点击任意边即可更改其类型或删除它。

CLI 与 MCP 集成

提供完整的命令行工作流支持（npm install -g @thask-org/cli）。提供 25 种 MCP 工具，支持 AI Agent 集成——Claude Code 和 Cursor 可以直接查询和修改你的图谱。支持一步式浏览器登录（thask login）和就地升级（thask self-update）。CLI 参考 · MCP 指南

按键权限与来源信息（v0.5.9+）

每个 API 密钥都归类为 user_interactive、agent 或 service，并具有 7 个独立的权限标志。Agent 密钥默认禁止语义写入（描述、“原因”内容）和节点验证——因此，幻觉生成的描述不会悄然写入你的图谱。每次写入都会将 6 个维度的来源信息（执行者、渠道、Agent 模型、变更类型、触发条件、证据）记录到单个 audit_log 表中。DATABASE.md > 来源信息

建议队列

希望修改描述的 Agent 会将建议提交到 node_suggestions，由人工批准后再应用更改。作出决定的人工用户将成为记录在案的作者——Agent 仅记录在审计元数据中。此规则由服务端强制执行：无论权限标志如何，accepted 决策都必须由 user_interactive 执行者作出。

批量操作（v0.5.10+）

三个端点将 N 次往返请求减少到一次——node.batch_update（最多 200 个）、edge.batch_create / edge.batch_delete（最多 500 个）。权限或循环检测失败时会原子回滚；skipped[] 中会列出每项跳过原因；任何项目被跳过时返回 HTTP 207 Multi-Status。大幅节省 Agent 上下文（1 次调用，而非 N 次）。

本地优先的 CLI 遥测（v0.5.15+）

每次 CLI 调用、MCP 工具调用和 HTTP 响应都会向 ~/.thask/events.jsonl 追加一行 JSONL——数据仅保存在你的设备上，不会上传。可通过 thask usage 查看（30 天摘要、p50/p95 延迟、热门命令），通过 thask reflog / thask history 查看（近期事件、全文搜索），也可以直接对文件执行 tail -f。原始请求体需手动选择启用（thask telemetry config set capture_payloads true）；默认只采集元数据。Token、URL 凭据、JWT 和 Cookie 会在写入时脱敏。

Go 依赖扫描器

扫描 Go 代码库，自动生成依赖图。thask scan --path . 会解析 go.mod 和导入项，自动创建节点和边。可通过插件系统扩展。

图分析

检测依赖循环（Tarjan DFS）并查找关键路径（最长的 depends_on/blocks 链）。切换分析模式（Shift+A），即可在画布上直观查看循环和关键路径。

外部 API（v1）

面向第三方集成的版本化 REST API，位于 /api/v1/。提供 OpenAPI 3.1 规范、交互式 Scalar 文档、结构化错误响应和幂等性支持。API 指南

基于角色的访问控制

提供四种团队角色——Owner、Admin、Member、Viewer，并支持细粒度权限。每个项目可单独设置角色（Editor、Viewer）。支持通过 API 密钥进行编程访问。

项目共享

通过链接共享项目，并授予查看者或编辑者权限。可为每个项目的成员分配细粒度角色。公开的共享视图支持实时协作。支持可嵌入的图视图和 OG 图片生成。

模板

使用内置模板创建新项目：API 流程、微服务地图、冲刺看板。在项目创建流程中即可一键应用。

主题系统

支持浅色和深色模式，并可检测系统设置。按用户保存主题设置。整个设计系统均使用 CSS 变量。

---

工作原理

Thask 由两部分组成：

	服务端（可自托管）	CLI（本地）
内容	Web UI + REST API + PostgreSQL	终端命令 + MCP 服务
安装	docker compose up	npm install -g @thask-org/cli
使用者	人类（浏览器）	人类（终端）+ AI Agent（MCP）
数据	存储所有内容（节点、边、用户）	通过服务端 API 读写

Browser ──→ Thask Server (Docker) ──→ PostgreSQL
                ↑
CLI / MCP ──────┘

服务端运行你的图数据库和 Web UI。CLI与服务端的 API 通信——你可以在终端中创建节点、运行扫描并分析图。AI Agent（Claude Code、Cursor）使用 CLI 内置的 MCP 服务。

---

AI Agent 快速入门

只需 2 分钟，即可让 Claude Code 与 Thask 配合使用：

1. 启动 Thask（如果尚未运行）：

   make up
   

2. 安装 CLI 并通过浏览器登录：

   npm install -g @thask-org/cli
   thask config set url http://localhost:7244
   thask login   # opens browser, click Approve, token saved
   

   thask login（v0.5.11+）取代了旧的操作流程：“在 Settings 中创建密钥， 复制 64 个字符的字符串，再粘贴”。MCP 服务会读取同一个 ~/.thask/config.json，因此这一次登录也适用于 Claude Code。 对于无头环境 / SSH 会话：在 Web UI 中创建密钥，然后运行 thask config set token <key>。

3. 添加到 Claude Code（.claude/mcp.json）：

   {
     "mcpServers": {
       "thask": {
         "command": "thask",
         "args": ["mcp", "serve"]
       }
     }
   }
   

现在，Claude Code 可以读取和修改你的依赖图——v0.5.9+ 的权限控制可确保 Agent 密钥无法悄无声息地写入幻觉生成的描述。详情请参阅 MCP 指南，如需零配置安装，请参阅官方 Claude Code 插件。

---

快速入门

Docker（推荐）

make up   # auto-generates .env with SESSION_SECRET on first run

或手动操作：

cp .env.example .env
# Edit .env and set SESSION_SECRET (or let make generate it)
docker compose up --build

打开 http://localhost:7243 并创建账户。

本地开发（macOS / Linux）

Makefile 是唯一可信来源——每个开发工作流都有对应的目标。

make dev          # one-shot: starts DB + capture worker, then backend + frontend in parallel

或者在不同终端中单独运行各个部分：

make dev-db       # PostgreSQL only (docker compose)
make dev-capture  # Playwright capture worker (docker compose)
make dev-backend  # Go backend (requires air: go install github.com/air-verse/air@latest)
make dev-frontend # SvelteKit frontend on :7243

如果未安装 air，请直接运行后端：

cd backend && cp .env.example .env && go run ./cmd/server

本地开发（Windows）

前置条件：Go 1.26+、Node.js 22+、Docker Desktop

# Terminal 1 — Start PostgreSQL
docker compose -f docker-compose.dev.yml up -d

# Terminal 2 — Start backend
cd backend
copy .env.example .env
go run ./cmd/server

# Terminal 3 — Start frontend
cd frontend
copy .env.example .env
npm install
npm run dev -- --port 7243

提示： 要在 Windows 上使用 make，请通过 scoop install make 或 choco install make 安装。

打开 http://localhost:7243

---

技术栈

层	技术
后端	Go 1.26（Echo v4）
前端	SvelteKit + Svelte 5（runes）
CLI	Go（Cobra）+ MCP 服务
图引擎	Cytoscape.js + fCOSE 布局 + edgehandles
样式	Tailwind CSS v4
状态	Svelte 5 runes（$state、$derived、$effect）
数据库	PostgreSQL 17 + pgx/v5（原生 SQL）
身份验证	基于会话（bcrypt + 仅 HTTP 的 Cookie）
测试	Go test（单元测试 + 基准测试）+ Playwright（E2E）
部署	Docker Compose（3 个服务）
npm	@thask-org/cli（esbuild 模式，5 个平台）

---

项目结构

backend/
  cmd/server/           # Go entrypoint, route registration
  internal/
    config/             # Environment configuration
    dto/                # Request/response structs, v1 errors, pagination
    handler/            # HTTP handlers (auth, team, node, edge, impact,
                        #   graph_analysis, activity, events, og_image, api_key)
    middleware/         # Auth, role, project access, shared access,
                        #   idempotency, v1 response
    model/              # Domain models & enums
    repository/         # Database access layer (pgx, 11 repos)
    service/            # Business logic (waterfall, impact, graph_analysis,
                        #   layout, eventhub, auth)
    migrate/            # Migration runner
  migrations/           # SQL migration files (001~005)
  api/                  # OpenAPI spec + API guide

frontend/
  src/
    routes/
      login/            # Login page
      register/         # Register page
      dashboard/        # Dashboard & team pages
        [teamSlug]/
          [projectId]/  # Graph editor page
          members/      # Team member management
        settings/       # User settings
      shared/[shareToken]/  # Public shared view
      embed/[shareToken]/   # Embeddable graph
      docs/             # Documentation page
    lib/
      api.ts            # Typed API client
      types.ts          # TypeScript type definitions
      markdown.ts       # Markdown renderer (marked + DOMPurify)
      stores/           # Svelte 5 rune stores (auth, graph, teams,
                        #   members, realtime, theme, undo)
      components/       # CytoscapeCanvas, GraphToolbar, DetailSidePanel,
                        #   MarkdownEditor, ActivityFeed, TemplateSelector,
                        #   ShareDialog, SearchBar, ProjectMenu, AddNodeModal
      cytoscape/        # Styles, layouts, impact, sync, resize,
                        #   portOverlay, groupHelpers, statusDot
      managers/         # nodeCrud, edgeCrud
  e2e/                  # Playwright E2E tests
  static/templates/     # Built-in project templates (3)

cli/
  cmd/thask/            # CLI entrypoint
  internal/
    cmd/                # Cobra commands (node, edge, team, project,
                        #   graph, impact, scan, mcp, auth, config,
                        #   aliases, install, version)
    mcp/                # MCP server (stdio protocol, 12+ tools)
    scan/               # Go dependency scanner + plugin runner
    client/             # HTTP client for backend API
    config/             # Config file management (~/.config/thask/)
    output/             # Output formatting (JSON, table, quiet)

npm/                    # npm distribution (@thask-org/cli, 5 platforms)

---

数据模型

Users ──< TeamMembers >── Teams ──< Projects ──< Nodes ──< NodeHistory
  │                                    │            │
  └──< ApiKeys                         │            └──< Edges
                                       │
                                       └──< ProjectMembers >── Users

节点类型： FLOW BRANCH TASK BUG API UI GROUP REQUIREMENT DECISION EXPERIMENT PERSON 节点状态： PASS FAIL IN_PROGRESS BLOCKED 节点生命周期状态（v0.6.0）： 自由格式文本，与 status 正交。用于 REQUIREMENT/DECISION/EXPERIMENT/PERSON（例如 APPROVED、RUNNING、DECIDED、ACTIVE）。 边类型： depends_on blocks related parent_child triggers realizes conflicts drives supersedes tests produced owns decided reported 侧表（v0.6.0）： node_comments、node_attachments、project_tags

---

环境变量

后端（backend/.env）

变量	说明	默认值
DATABASE_URL	PostgreSQL 连接字符串	postgresql://thask:thask_dev_password@localhost:7242/thask
SESSION_SECRET	用于会话签名的随机字符串	—
PORT	后端服务端口	7244
FRONTEND_URL	用于 CORS 的前端 URL	http://localhost:7243
CAPTURE_URL	Playwright 内部捕获工作进程 URL	http://localhost:7241
CAPTURE_INTERNAL_SECRET	后端 → 捕获工作进程调用时使用的可选共享密钥	—
CAPTURE_TIMEOUT_SECONDS	捕获工作进程请求超时	30
V1_ALLOWED_ORIGINS	/api/v1/ 的逗号分隔 CORS 源	*
MAX_REQUEST_BODY_BYTES	v1 路由的最大请求正文大小（字节）	1048576（1MB）
THASK_ATTACHMENT_DIR	v0.6.0 节点附件的根目录。留空 = 禁用附件（上传端点返回 503）。	—
THASK_ATTACHMENT_MAX_BYTES	附件上传的单文件最大大小	10485760（10MB）

前端（frontend/.env）

变量	说明	默认值
BACKEND_URL	后端 API URL（服务端代理）	http://localhost:7244

Docker Compose（.env）

变量	说明	默认值
SESSION_SECRET	必需。 用于会话签名的随机字符串，长度至少为 64 个字符	—
APP_URL	应用的公开 URL	http://localhost:7243
BACKEND_URL	前端代理使用的后端 URL	http://backend:7244
POSTGRES_PASSWORD	PostgreSQL 密码	thask_password
CAPTURE_PORT	Playwright 捕获工作进程的本地/开发主机端口	7241
CAPTURE_INTERNAL_SECRET	后端 → 捕获工作进程调用时使用的可选共享密钥	—
CAPTURE_FRONTEND_URL	捕获工作进程在 Chromium 中打开的 URL	http://frontend:7243
BROWSER_WS_ENDPOINT	捕获工作进程使用的 Browserless Chrome WebSocket 端点	ws://browserless:3000

部署到自定义域名

在 .env 中将 APP_URL 设置为你的公开 URL：

# .env
APP_URL=https://thask.example.com
SESSION_SECRET=your-random-64-char-string

这会自动配置 CORS 和 CSRF 保护。BACKEND_URL 无需更改——前端服务器会通过内部 Docker 网络将 API 请求代理到后端。

Browser ──https──▶ Reverse Proxy (nginx/Cloudflare)
                        │
                        ▼ :7243
                   Frontend (SvelteKit)
                        │
                        ▼ http://backend:7244 (Docker internal)
                   Backend (Go)
                        │
                        ▼ http://capture:7241 (Docker internal, optional)
                   Capture Worker (Playwright)
                        │
                        ▼ postgres:5432 (Docker internal)
                   PostgreSQL

在前端部署反向代理（例如 nginx、Caddy、Cloudflare Tunnel）来处理 SSL 终止。

---

文档

• 架构 — 分层、数据流、目录结构
• 数据库 — ER 图、表、索引、关系
• API 参考 — 30 多个端点及请求/响应示例
• 图引擎 — 节点类型、边类型、GROUP、影响模式
• 键盘快捷键 — 所有快捷键和交互
• CLI 参考 — 安装、命令、Shell 别名
• MCP 指南 — AI Agent 集成（Claude Code、Cursor）
• Claude Code 插件 — 在每个会话中自动注入项目上下文并注册 MCP 服务
• 扫描器插件 — 用于支持新语言的扫描器插件系统
• V1 API 指南 — 面向第三方开发者的外部 API 快速入门

---

Makefile 命令

完整功能集——make 是开发、构建、测试和发布的规范入口。

开发

命令	说明
make dev	启动 DB 和捕获工作进程，然后并行启动后端和前端
make dev-services	启动 DB 和捕获工作进程（docker compose）
make dev-db	仅启动 PostgreSQL
make dev-backend	使用 air 热重载运行 Go 后端
make dev-frontend	在 :7243 上运行 SvelteKit 前端
make dev-capture	构建并启动 Playwright 捕获工作进程
make db-up / make db-down	启动 / 停止开发用 PostgreSQL 容器

构建与发布

命令	说明
make build	构建 CLI、后端（backend/bin/server）和前端
make build-cli	将 CLI 二进制文件构建到 bin/thask（包含版本和提交 ldflags）
make release-cli	为 5 个平台交叉编译 CLI、打标签、推送、发布到 npm、创建 GitHub Release。设置 CLI_VERSION=x.y.z（或从 cli/package.json 读取）。npm 双重身份验证可选设置 THASKOTP=...。

测试

命令	说明
make test	后端 Go 测试和前端检查
make test-backend	后端 Go 测试（详细输出）
make test-cli	CLI Go 测试
make test-e2e	Playwright E2E 测试
make bench	扫描器和图分析基准测试

Docker

命令	说明
make up	通过 Docker Compose 启动完整技术栈（首次运行时自动生成包含 SESSION_SECRET 的 .env）
make down	停止 Docker Compose
make clean	删除 backend/bin、bin/、dist/、frontend/build、frontend/.svelte-kit

---

路线图

v0.1 — 基础（已完成）

• 图 CRUD（节点、边、分组）
• 7 种节点类型和 4 种状态的可视化样式
• fCOSE 自动布局和手动定位
• 拖放分组和复合节点
• 节点搜索和键盘快捷键
• QA 影响分析（基于 BFS）
• 状态逐级传播
• 基于会话的身份验证和团队管理
• 通过 Docker Compose 一键部署
• Go 后端，包含 18 个单元测试
• Playwright E2E 测试（13 个测试）
• 支持完整图操作的 CLI 工具
• 用于 AI Agent 集成的 MCP 服务（12 个工具）
• API 密钥身份验证（Bearer 令牌）
• 基于角色的访问控制（owner/admin/member/viewer）
• 团队成员管理（邀请、角色、转让）
• 通过公开链接共享项目（viewer/editor 模式）
• CLI 共享命令（share、unshare、invite、kick）

v0.2 — 外部 API 与协作（已完成）

• 通过 SSE 实现实时协作
• 将图导出为 PNG / JSON
• 导入图（替换/合并模式）
• 版本化外部 API（/api/v1/），附带 OpenAPI 规范
• 交互式 API 文档（/api/v1/docs 上的 Scalar UI）
• v1 的结构化错误响应
• 为 API 使用者提供幂等性支持
• 为外部域名配置 CORS
• 边路径点（可拖动的折点）
• 使用吸附参考线渲染 SVG 边
• 可嵌入的图视图（/embed/:shareToken）
• 为分享链接生成 OG 图片

v0.3 — 扫描器 + 图智能（已完成）

• Go 依赖扫描器（thask scan），使用 go/ast 解析
• 循环检测（Tarjan DFS）和关键路径分析
• 分析模式前端（Shift+A 切换，突出显示循环/关键路径）
• MCP 工具：thask.scan.run、thask.graph.analyze
• GitHub Actions CI（后端测试、CLI 测试、前端检查）
• 扫描器插件系统及文档

v0.4 — 社区与生态系统（已完成）

• npm 分发（@thask-org/cli、5 个平台二进制文件、esbuild 模式）
• 扫描器插件接口（任何输出 ImportGraphRequest JSON 的可执行程序）
• Homebrew formula 模板
• 性能基准测试（扫描器 + 图分析）

v0.5 — 视觉优化与分析（已完成）

• 支持系统检测的浅色/深色主题系统
• 活动动态（近期变更及用户署名）
• 项目模板（API 流程、微服务地图、冲刺看板）
• 全面应用 Amber Precision 设计系统
• Markdown 描述渲染（marked + DOMPurify）
• v0.5.6 — 图像捕获（通过 Playwright worker 生成 PNG/SVG）
• v0.5.8 — TypeScript/JavaScript 依赖扫描器（别名解析、SvelteKit $lib）
• v0.5.9 — 按密钥设置权限 + 建议队列 + 六维 audit_log（防幻觉保护）
• v0.5.10 — 批量端点（node.batch_update、edge.batch_*），支持 HTTP 207 部分成功；thask self-update
• v0.5.11 — thask login 浏览器身份验证；URL 自动规范化

v0.6 — 知识 OS 基础（已完成）

• v0.6.0 — 新增 4 种节点类型（REQUIREMENT、DECISION、EXPERIMENT、PERSON）
• v0.6.0 — 新增 9 种边动词（realizes、conflicts、drives、supersedes、tests、produced、owns、decided、reported）
• v0.6.0 — 领域生命周期状态字段（与 status 正交）
• v0.6.0 — 每条边的 JSONB metadata
• v0.6.0 — 节点评论串（node_comments）
• v0.6.0 — 每个节点的文件附件（node_attachments + THASK_ATTACHMENT_DIR 卷）
• v0.6.0 — 规范项目标签（project_tags）
• v0.6.0 — 按项目限定 API 密钥范围

未来

• 图版本快照与差异比较
• 节点生命周期分析（状态停留时间、瓶颈检测）
• 图变更时触发 Webhook
• GitHub 仓库同步（推送时自动更新图）
• Slack / Discord 通知
• 移动端响应式布局
• 可自托管的 SSO（SAML / OIDC）

---

贡献

欢迎贡献！设置说明和指南请参阅 CONTRIBUTING.md。

---