项目定位与目标

Harmony Plugin 是一个面向 Harmony 项目管理平台的双模式工具集，同时提供 命令行界面 (CLI) 与 Claude Code 插件 (MCP 服务器 + 工作流技能) 两种使用形态。资料来源：README.md:1-3

项目通过 Supabase 后端与 Harmony 云端服务通信，覆盖任务（tasks）、史诗（epics）、里程碑（milestones）、迭代（cycles）、子任务（subtasks）、验收标准（ac）、测试用例（tests）、项目文档（docs）以及工作区知识库（knowledge）的全生命周期管理。资料来源：README.md:23-44

系统分层架构

graph TB
    User[用户 / 开发者] --> CLI[CLI 入口<br/>commander]
    User --> Claude[Claude Code]
    Claude --> MCP[MCP 服务器<br/>@modelcontextprotocol/sdk]
    CLI --> Tools[工具层<br/>src/tools/*]
    MCP --> Tools
    Tools --> Supabase[(Supabase 后端)]
    CLI --> Cfg[本地配置<br/>~/.harmony/config.json]
    MCP --> Cfg

系统采用清晰的分层设计：

• 入口层：CLI 通过 commander 框架解析命令与参数，并按领域拆分子命令模块（tasks / epics / milestones / knowledge 等），资料来源：src/cli/commands/subtasks.ts:1-30
• 认证层：基于 HarmonyAuth 包装 API Token，并通过 createAuthenticatedClient 构建已认证的 Supabase 客户端，资料来源：src/cli/commands/auth.ts:1-20
• 配置层：本地配置存储于 ~/.harmony/config.json（目录权限 0700，文件权限 0600），支持多项目并存与切换，资料来源：src/cli/config.ts:14-47
• 工具层：封装领域逻辑（任务、评论、活动、知识库等），对上提供统一的 (client, projectId, userId, params) 调用契约
• 格式化层：通过 formatTable / formatDetail / formatOutput 渲染表格、详情与 JSON 输出，资料来源：src/cli/formatter.test.ts:1-25

核心能力矩阵

主要运行依赖包括 @modelcontextprotocol/sdk、@supabase/supabase-js、commander、chalk、cli-table3 与 zod，构建与测试工具链为 esbuild + typescript + vitest，资料来源：package.json:20-35

工作流与集成模式

CLI 提供两种输出模式：Text（默认带色彩与表格）与 JSON（通过 --json 启用，便于脚本管道），由 formatOutput 统一调度，资料来源：src/cli/formatter.test.ts:5-10。多项目场景下，登录后默认激活当前项目，可通过 harmony project switch <name> 切换本地激活项目，资料来源：src/cli/commands/project.ts:1-25

作为 Claude Code 插件时，插件同时挂载 MCP 服务器（基于 @modelcontextprotocol/sdk）与两个工作流技能：start-work（拉取/创建任务、切换为 In Progress、创建 git worktree）与 finish-work（rebase、squash 合并、清理 worktree、任务置为 Done），资料来源：README.md:69-78

首次安装后，通过 /harmony-setup 技能将 API Token 写入 .claude/settings.local.json（确保该文件位于 .gitignore），并调用 mcp__harmony__list_tasks 验证连通性，最后提示用户重启 Claude Code 以使新 Token 生效，资料来源：commands/harmony-setup.md:5-40

See Also

• 配置与多项目切换
• CLI 命令参考
• MCP 服务器与 Claude Code 集成
• 工作流技能：start-work / finish-work

概述

harmony 命令行工具是 Harmony 项目管理平台的终端入口，提供任务、Epic、里程碑、周期、标签、文档、测试用例、知识库等资源的 CRUD 与查询能力。CLI 基于 commander@^13.1.0 构建命令树，使用 chalk@^5.4.1 着色输出、cli-table3 渲染表格，并通过 zod@^3.25.0 进行入参校验（资料来源：package.json:dependencies）。

CLI 同时也是 MCP 插件（harmony-plugin）的运行时后端，Claude Code 通过同一套 src/tools/* 工具函数与 Supabase 后端通信，从而在终端与编辑器代理中获得一致的行为（资料来源：README.md、src/cli/index.ts）。

命令注册架构

CLI 入口文件 src/cli/index.ts 通过 createRequire 读取 package.json 中的版本号，创建 Command 实例并按顺序注册各命令分组：registerAuthCommands、registerTaskCommands、registerQueryCommand、registerCommentCommands、registerProjectCommands、registerMemberCommands、registerActivityCommand、registerEpicCommands、registerLabelCommands、registerMilestoneCommands、registerCycleCommands、registerChecklistCommands、registerAcceptanceCriteriaCommands、registerDependencyCommands、registerTestCaseCommands、registerBulkCommands、registerKnowledgeCommands、registerSubtaskCommands。全局 program 还提供 --json 选项，便于脚本化输出 JSON 结果（资料来源：src/cli/index.ts:1-19）。

每个命令分组都遵循相同的模式：通过 runCommand(program.opts(), …) 包装器获取已认证的 ctx（包含 client、projectId、userId），再调用 src/tools/* 中的纯函数完成业务请求，最后用 formatTable / formatDetail 渲染输出（资料来源：src/cli/commands/milestones.ts:1-9、src/cli/commands/cycles.ts:1-9）。

flowchart TD
    A[harmony CLI 入口] --> B[commander 程序]
    B --> C1[auth: login/logout]
    B --> C2[project: info/switch]
    B --> C3[tasks: list/get/create/update/query]
    B --> C4[comments: list/comment]
    B --> C5[epics/labels/milestones/cycles]
    B --> C6[ac/subtasks/dependencies/tests]
    B --> C7[knowledge/docs/activity/members]
    C3 --> D[runCommand 包装器]
    C5 --> D
    C7 --> D
    D --> E[src/tools/* 工具函数]
    E --> F[(Supabase 后端)]
    D --> G[formatter: 表格/详情]

认证流程

CLI 认证基于 Harmony API Token，通过 --token 选项在 harmony login 中提供。registerAuthCommands 接收必填的 --token、可选的 --name、--supabase-url、--supabase-anon-key。若未提供 --name，会调用 getProject(client, projectId) 自动从项目名派生出小写连字符形式的名字（资料来源：src/cli/commands/auth.ts:8-19）。

认证成功后，token 与可选的 Supabase 自定义配置被写入 ~/.harmony/config.json（权限 0o600），并将该项目设为 activeProject。HarmonyAuth 负责解析 token、提取 projectId，createAuthenticatedClient 则基于此创建已签名的 Supabase 客户端。harmony logout <name> 移除指定项目，若移除的是当前激活项目则将 activeProject 置为 null（资料来源：src/cli/config.ts:1-49、src/cli/commands/auth.ts:1-25）。

多项目支持由 loadConfig / saveConfig / addProject / switchProject / removeProject 实现：所有项目保存在 projects 字典中，activeProject 字符串指向当前使用的那一个（资料来源：src/cli/config.ts:1-60）。harmony projects 列出所有项目并以 * 标记激活项，harmony project switch <name> 切换激活项目（资料来源：src/cli/commands/project.ts:1-18、README.md）。

核心命令分组

CLI 命令按领域划分为若干顶级子命令。下表汇总了主要分组及其典型子命令（资料来源：src/cli/index.ts:8-19、README.md）：

任务 ID 接受多种形式：UUID、纯数字或 B-123 这类带前缀的编号。命令实现中通过 taskId 直接传入工具函数，后端负责解析。子任务可通过 parent 子命令查看任务的直接父级，或用 add / remove 附加/分离子任务（资料来源：src/cli/commands/subtasks.ts:1-25）。

知识库命令支持按 --type（architecture/business/convention/specification）、--status、多次出现的 --tag、--search 过滤，--all 包含已废弃条目。create 子命令接受 --source-task <id> 将知识条目与具体任务关联（资料来源：src/cli/commands/knowledge.ts:1-25）。活动流命令 harmony activity <task-id> 通过 buildActivitySummary 区分评论与事件，将 field_name: old → new 形式的变化序列化为可读摘要（资料来源：src/cli/commands/activity.ts:1-20）。

配置与目录布局

CLI 配置文件路径可通过环境变量 HARMONY_CONFIG_DIR 覆盖，默认值为 ~/.harmony，文件名为 config.json。目录以 0o700 创建、文件以 0o600 写入，确保仅当前用户可读（资料来源：src/cli/config.ts:1-20）。

HarmonyConfig 接口定义两个核心字段：activeProject: string | null 与 projects: Record<string, ProjectConfig>，其中 ProjectConfig 包含 name、token、可选的 supabaseUrl 与 supabaseAnonKey。addProject 在新增项目时会同时设为激活项目；switchProject 仅修改 activeProject 字段（资料来源：src/cli/config.ts:1-60）。

在 MCP 插件场景下，API Token 优先从 .claude/settings.local.json 的 env.HARMONY_API_TOKEN 读取；/harmony-setup 技能负责保存 token 并调用 mcp__harmony__list_tasks 验证连通性，最后提示用户重启 Claude Code 让 MCP 服务加载新凭证（资料来源：commands/harmony-setup.md:1-30）。

常见使用模式

最常见的脚本化用法是结合 --json 标志：

harmony login --token <token>            # 登录并将项目设为激活
harmony projects                          # 查看已登录项目
harmony project switch my-other-project   # 切换激活项目
harmony tasks list --json | jq '.[].title'  # 提取所有任务标题
harmony tasks update B-42 --status "In Progress"
harmony milestones ship <milestone-id>    # 发布里程碑（自动清理非 Done 任务）

故障排查

• 命令找不到：命令分组未注册或名称拼写错误，确认使用的是顶级子命令而非已废弃的别名（资料来源：src/cli/index.ts:8-19）。
• 认证失败：检查 ~/.harmony/config.json 中 activeProject 是否指向仍存在的项目；token 失效时重新执行 harmony login --token <new>（资料来源：src/cli/config.ts:1-60）。
• MCP 服务未生效：首次安装或更换 token 后必须重启 Claude Code，hook 与 MCP 服务只在启动时加载（资料来源：README.md、commands/harmony-setup.md）。
• removeProject 抛出 "not found"：项目名在 config.json 中不存在，使用 harmony projects 查看准确名称（资料来源：src/cli/config.test.ts:1-30）。

See Also

• README.md — 项目总览与安装说明
• commands/harmony-setup.md — MCP 插件 Token 配置技能
• src/tools/* — CLI 与 MCP 共用的工具层实现
• Supabase 后端 API 文档（外部）

研究文档（引用来源参考）

(no reference document available)

概览

Harmony 插件同时提供 CLI 与 MCP 服务器两个入口，二者共享同一套数据访问工具函数。CLI 使用 Commander.js 解析参数并以 src/tools/* 下的纯函数封装对 Supabase 后端的调用；MCP 服务器则基于 @modelcontextprotocol/sdk 将同一批工具暴露给 Claude Code 调用。package.json 中 @modelcontextprotocol/sdk 与 @supabase/supabase-js 并列为运行时依赖，佐证了这一双前端、单后端的架构。资料来源：package.json、README.md

整体架构

graph TB
  subgraph "前端入口"
    CLI["CLI 进程 (harmony)<br/>Commander.js"]
    MCP["MCP Server<br/>@modelcontextprotocol/sdk"]
  end
  subgraph "工具层 src/tools/*"
    T1[tasks]
    T2[comments]
    T3[milestones]
    T4[dependencies]
    T5[knowledge]
    Tn[acceptance-criteria<br/>subtasks · cycles · epics ...]
  end
  subgraph "支撑模块"
    Auth[auth.ts · HarmonyAuth]
    Sup[supabase.ts · createAuthenticatedClient]
    Cfg[config.ts · 本地多项目]
    RC[run-command.ts · 上下文与错误处理]
  end
  Backend[(Supabase 后端<br/>PostgREST + RLS)]
  CLI --> RC
  MCP --> T1
  RC --> T1
  Auth --> Sup
  Sup --> T1
  T1 --> Backend
  Cfg --> RC

CLI 命令注册模式

CLI 入口在 src/cli/index.ts 中以 Commander 创建根命令 harmony，声明全局 --json 选项，然后按序调用 registerAuthCommands、registerTaskCommands、registerQueryCommand、registerCommentCommands、registerProjectCommands、registerMemberCommands、registerActivityCommand、registerEpicCommands、registerLabelCommands、registerMilestoneCommands、registerCycleCommands、registerChecklistCommands、registerAcceptanceCriteriaCommands、registerDependencyCommands、registerTestCaseCommands、registerBulkCommands、registerKnowledgeCommands、registerSubtaskCommands。资料来源：src/cli/index.ts

每个子模块遵循统一三段式：

1. 取或建父命令。comments 模块先通过 program.commands.find((c) => c.name() === 'tasks') 找到 tasks 子命令，找不到则抛错。资料来源：src/cli/commands/comments.ts
2. 挂载子命令链。milestones 模块自建 milestones 父命令，再串联 list / create / update / ship，并以 --shipped / --planning 互斥状态过滤。资料来源：src/cli/commands/milestones.ts
3. action 内调用 runCommand。所有 action 处理器都向 runCommand(program.opts(), async (ctx) => toolFn(ctx.client, ctx.projectId, ctx.userId, params), formatter) 传入三个参数：上下文回调、工具函数、结果格式化函数。

格式化器分为两类：formatTable 用于列表输出（含列宽、日期与布尔值转换），formatDetail 用于单条记录展示。activity 模块演示了自定义摘要器——buildActivitySummary 根据 item.type 区分评论原文与字段变更事件，组合成 field_name: old → new 文本。资料来源：src/cli/commands/activity.ts

工具层与数据访问

src/tools/ 是 CLI 与 MCP 共享的纯函数层。从各命令文件的 import 语句可盘点出完整工具集：tasks、query、comments、project、members、activity、epics、labels、milestones、cycles、checklist、acceptance-criteria、dependencies、test-cases、bulk、knowledge、subtasks。命名约定区分查询与变更：纯读取为 listXxx / getXxx / queryXxx，写入为 createXxx / updateXxx / manageXxx。资料来源：src/cli/commands/acceptance-criteria.ts

工具函数签名一致——接收 (client, projectId, userId?, params)，返回 Promise<T>。dependencies 模块的 list 动作演示了双侧投影：先取出 data.depends_on 与 data.blocks 两条关系链，再把每条记录 map 成包含 task_number / title / status 的扁平行以适配表格输出。资料来源：src/cli/commands/dependencies.ts

knowledge 模块覆盖了最完整的工具形态：queryKnowledge 接受 type / status / tags / search / include_superseded 五类过滤；createKnowledgeEntry 接受 title / content / type / status / tags / source_task_id；updateKnowledgeEntry 与 supersedeKnowledgeEntry 处理知识条目的生命周期与版本替换。tags 选项通过 (v, prev) => [...prev, v] 实现命令行重复累加。资料来源：src/cli/commands/knowledge.ts

subtasks 模块则演示了"父→子"反查：parent 子命令调用 listParent 返回单条记录（父任务的 task_number / title / status），add / remove 子命令复用同一 manageSubtasks 工具，分别传入 { add: children } 与 { remove: children } 参数。资料来源：src/cli/commands/subtasks.ts

运行上下文与认证

runCommand 负责为每次调用组装 ctx，包含三件套：

• ctx.client：经过认证的 Supabase 客户端。
• ctx.projectId：当前活动项目 ID，源自本地配置。
• ctx.userId：当前用户 ID（部分写入工具需要）。

ctx 的构建依赖本地多项目配置层。config.ts 负责持久化，配置文件默认位于 ~/.harmony/config.json，可通过 HARMONY_CONFIG_DIR 覆盖；目录以 0o700 创建，文件以 0o600 写入；数据结构为 { activeProject: string | null, projects: Record<string, ProjectConfig> }，每条 ProjectConfig 至少含 name 与 token，可附加 supabaseUrl / supabaseAnonKey。资料来源：src/cli/config.ts

登录流程在 auth.ts 中完成：new HarmonyAuth(opts.token) 解析 token → createAuthenticatedClient 建立 Supabase 客户端 → auth.getProjectId() 提取项目 ID → 若未提供 --name 则调用 getProject(client, projectId) 取后端项目名并 slugify → addProject 写入本地配置并设为 activeProject。project switch 走 switchProject，不发起任何网络请求，仅修改本地 activeProject。资料来源：src/cli/commands/auth.ts、src/cli/commands/project.ts

MCP 服务器侧

虽然 MCP 服务器实现不在本批次源码内，但依赖关系与配置流程已清晰：@modelcontextprotocol/sdk 提供协议层，MCP 进程同样调用 src/tools/*。Claude Code 侧由 commands/harmony-setup.md 负责配置——读取/写入 .claude/settings.local.json 中的 env.HARMONY_API_TOKEN，确保该文件加入 .gitignore，并以 mcp__harmony__list_tasks(limit: 1) 验证连通性。配置完成后需重启 Claude Code (/exit 再 claude)，让 MCP 进程在启动时读到新 token。资料来源：commands/harmony-setup.md

常见失败模式

See Also

• 项目概览与 CLI 命令清单：README.md
• 插件安装与 token 配置流程：commands/harmony-setup.md
• 本地多项目配置层：src/cli/config.ts
• 认证与登录实现：src/cli/commands/auth.ts
• CLI 入口与命令注册表：src/cli/index.ts

插件定位与组成

harmony-plugin 仓库同时承载 Harmony 的 CLI 工具与 Claude Code 插件两种形态。当作为 Claude Code 插件安装时，它向宿主注入三类能力：MCP 服务器、工作流技能（workflow skills）以及初始化斜杠命令 README.md。具体而言：

• MCP 服务器：以 TypeScript 实现，依赖 @modelcontextprotocol/sdk 与 @supabase/supabase-js；启用插件后会自动加载，工具名前缀统一为 mcp__harmony__（例如 mcp__harmony__get_task），覆盖任务、标签、评论、活动、文档、周期、里程碑以及批量操作 README.md package.json。
• 工作流技能：start-work 与 finish-work，封装"开工—收尾"回路 README.md。
• 设置命令：/harmony-setup，负责写入 API Token 并验证连通性 commands/harmony-setup.md。

MCP 入口在仓库根的 .mcp.json 中声明；插件描述与市场清单分别存放在 .claude-plugin/plugin.json 与 .claude-plugin/marketplace.json 中 README.md。

插件生命周期

从安装到可用，插件需依次经历四个阶段，全部在 Claude Code 会话内完成：

flowchart LR
    A[添加市场源<br/>/plugin marketplace add] --> B[安装插件<br/>/plugin install]
    B --> C[重启 Claude Code]
    C --> D[SessionStart Hook<br/>npm install + tsc 构建]
    D --> E{dist/index.js<br/>已存在?}
    E -- 否 --> F[构建并写入 dist/]
    E -- 是 --> G[跳过构建]
    F --> H
    G --> H[运行 /harmony-setup<br/>写入 HARMONY_API_TOKEN]
    H --> I[再次重启<br/>MCP 读取环境变量]
    I --> J[就绪：mcp__harmony__* 工具可用]

各阶段要点：

在 Claude Code 内依次执行 /plugin marketplace add ycomplex/harmony-plugin 与 /plugin install harmony-plugin@ycomplex README.md。

1. 市场与安装

重启后，SessionStart 钩子（在 hooks/hooks.json 中定义）会自动安装 npm 依赖并编译 TypeScript MCP 服务器，约耗时 10 秒；若 dist/index.js 已存在则跳过构建，实现会话级缓存 README.md。

1. 首次构建

/harmony-setup 命令读取项目根的 .claude/settings.local.json，在 env.HARMONY_API_TOKEN 字段写入 Token，并通过调用 mcp__harmony__list_tasks（limit=1）验证连通性；若失败则要求用户检查 Token commands/harmony-setup.md。

1. Token 配置

Token 仅在 Claude Code 进程重启后才会被 MCP 服务器读取，因此配置完成后必须再次 /exit 后启动 claude commands/harmony-setup.md。

1. 最终激活

CLI 侧走相同的认证通道：harmony login --token <token> 借助 HarmonyAuth 解析 Token 并调用 createAuthenticatedClient 获取 Supabase 客户端，凭据最终持久化到 ~/.harmony/config.json（默认权限 0o600，目录权限 0o700） src/cli/commands/auth.ts src/cli/config.ts。

自动化更新

为获得自动更新能力，可进入 /plugin 的 Marketplaces 选项卡，选择 ycomplex 并启用 auto-update；该机制依赖于 .claude-plugin/marketplace.json 中声明的版本字段 README.md。

工作流技能

start-work 与 finish-work 两个技能由独立的 SKILL.md 描述，组合成端到端开发回路：

技能细节见 skills/start-work/SKILL.md 等文件；其执行依赖官方 superpowers 插件提供的能力 README.md。

失败模式与排查

• 构建失败：首次会话若依赖安装中断，可删除 dist/index.js 让 SessionStart 钩子强制重建 README.md。
• Token 未生效：写完 settings.local.json 后忘记再次重启，表现为 MCP 调用返回未鉴权错误；/harmony-setup 第 4 步已显式提示 commands/harmony-setup.md。
• Token 泄露：/harmony-setup 强制将 .claude/settings.local.json 加入 .gitignore；采用手工配置时需自行核对 commands/harmony-setup.md。
• 多项目切换：CLI 与 Claude Code 插件彼此独立；切换项目需使用 harmony project switch <name> 更新 ~/.harmony/config.json 的 activeProject 字段 src/cli/config.ts。

See Also

• CLI 命令总览与输出模式：README.md
• /harmony-setup 步骤定义：commands/harmony-setup.md
• 多项目本地配置与文件权限：src/cli/config.ts
• 登录与认证客户端初始化：src/cli/commands/auth.ts

Pitfall Log / 踩坑日志

项目：ycomplex/harmony-plugin

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/ycomplex/harmony-plugin | host_targets=mcp_host, claude_code, claude

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/ycomplex/harmony-plugin | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/ycomplex/harmony-plugin | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/ycomplex/harmony-plugin | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/ycomplex/harmony-plugin | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/ycomplex/harmony-plugin | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/ycomplex/harmony-plugin | release_recency=unknown