# https://github.com/ycomplex/harmony-plugin 项目说明书
生成时间：2026-06-23 18:12:14 UTC
## 目录
- [项目概述与系统架构](#page-1)
- [CLI 命令、认证与配置](#page-2)
- [MCP 服务器、工具注册表与数据访问层](#page-3)
- [Claude Code 插件生命周期与工作流技能](#page-4)
## 项目概述与系统架构
### 相关页面
相关主题：[CLI 命令、认证与配置](#page-2), [MCP 服务器、工具注册表与数据访问层](#page-3), [Claude Code 插件生命周期与工作流技能](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/ycomplex/harmony-plugin/blob/main/README.md)
- [package.json](https://github.com/ycomplex/harmony-plugin/blob/main/package.json)
- [src/cli/config.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/config.ts)
- [src/cli/commands/auth.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/auth.ts)
- [src/cli/commands/subtasks.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/subtasks.ts)
- [src/cli/commands/activity.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/activity.ts)
- [src/cli/commands/knowledge.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/knowledge.ts)
- [src/cli/formatter.test.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/formatter.test.ts)
- [commands/harmony-setup.md](https://github.com/ycomplex/harmony-plugin/blob/main/commands/harmony-setup.md)
# 项目概述与系统架构
## 项目定位与目标
Harmony Plugin 是一个面向 [Harmony](https://github.com/ycomplex/harmony-web) 项目管理平台的双模式工具集，同时提供 **命令行界面 (CLI)** 与 **Claude Code 插件 (MCP 服务器 + 工作流技能)** 两种使用形态。资料来源：[README.md:1-3]()
项目通过 [Supabase](https://supabase.com) 后端与 Harmony 云端服务通信，覆盖任务（tasks）、史诗（epics）、里程碑（milestones）、迭代（cycles）、子任务（subtasks）、验收标准（ac）、测试用例（tests）、项目文档（docs）以及工作区知识库（knowledge）的全生命周期管理。资料来源：[README.md:23-44]()
## 系统分层架构
```mermaid
graph TB
User[用户 / 开发者] --> CLI[CLI 入口
commander]
User --> Claude[Claude Code]
Claude --> MCP[MCP 服务器
@modelcontextprotocol/sdk]
CLI --> Tools[工具层
src/tools/*]
MCP --> Tools
Tools --> Supabase[(Supabase 后端)]
CLI --> Cfg[本地配置
~/.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]()
## 核心能力矩阵
| 命令域 | 主要操作 | 来源文件 |
|--------|----------|----------|
| 项目认证 | login / logout / projects / switch | `src/cli/commands/auth.ts`、`src/cli/config.ts` |
| 任务管理 | list / get / create / update / query / bulk-* | `README.md:23-32` |
| 子任务 | list / add / update / delete / parent | `src/cli/commands/subtasks.ts` |
| 评论与活动 | comments / comment / activity | `src/cli/commands/comments.ts`、`src/cli/commands/activity.ts` |
| 知识库 | knowledge list / create / update / supersede | `src/cli/commands/knowledge.ts` |
| 里程碑 | list / create / update / ship | `src/cli/commands/milestones.ts` |
主要运行依赖包括 `@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 ` 切换本地激活项目，资料来源：[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
- [配置与多项目切换](config.md)
- [CLI 命令参考](cli-commands.md)
- [MCP 服务器与 Claude Code 集成](mcp-server.md)
- [工作流技能：start-work / finish-work](workflow-skills.md)
---
## CLI 命令、认证与配置
### 相关页面
相关主题：[项目概述与系统架构](#page-1), [MCP 服务器、工具注册表与数据访问层](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [src/cli/index.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/index.ts)
- [src/cli/commands/auth.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/auth.ts)
- [src/cli/commands/project.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/project.ts)
- [src/cli/commands/tasks.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/tasks.ts)
- [src/cli/commands/milestones.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/milestones.ts)
- [src/cli/commands/cycles.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/cycles.ts)
- [src/cli/commands/knowledge.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/knowledge.ts)
- [src/cli/commands/comments.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/comments.ts)
- [src/cli/commands/activity.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/activity.ts)
- [src/cli/config.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/config.ts)
- [commands/harmony-setup.md](https://github.com/ycomplex/harmony-plugin/blob/main/commands/harmony-setup.md)
- [package.json](https://github.com/ycomplex/harmony-plugin/blob/main/package.json)
- [README.md](https://github.com/ycomplex/harmony-plugin/blob/main/README.md)
# CLI 命令、认证与配置
## 概述
`harmony` 命令行工具是 Harmony 项目管理平台的终端入口，提供任务、Epic、里程碑、周期、标签、文档、测试用例、知识库等资源的 CRUD 与查询能力。CLI 基于 [commander@^13.1.0](https://github.com/tj/commander.js) 构建命令树，使用 [chalk@^5.4.1](https://github.com/chalk/chalk) 着色输出、[cli-table3](https://github.com/cli-table/cli-table3) 渲染表格，并通过 [zod@^3.25.0](https://github.com/colinhacks/zod) 进行入参校验（资料来源：[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]()）。
```mermaid
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 ` 移除指定项目，若移除的是当前激活项目则将 `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 ` 切换激活项目（资料来源：[src/cli/commands/project.ts:1-18]()、[README.md]()）。
## 核心命令分组
CLI 命令按领域划分为若干顶级子命令。下表汇总了主要分组及其典型子命令（资料来源：[src/cli/index.ts:8-19]()、[README.md]()）：
| 分组 | 关键子命令 | 用途 |
|------|------------|------|
| `auth` | `login` / `logout` | 添加/移除项目凭证 |
| `project` | `info` / `switch` | 查看/切换当前项目 |
| `tasks` | `list` / `get` / `create` / `update` / `query` / `bulk-create` / `bulk-update` | 任务 CRUD 与高级搜索 |
| `comments` | `comments` / `comment` | 任务评论查看与新增 |
| `epics` | `list` / `create` / `update` | Epic 管理 |
| `milestones` | `list` / `create` / `update` / `ship` | 里程碑管理（含发布动作） |
| `cycles` | `list` / `create` / `update` | 周期管理（首周期需手动创建） |
| `labels` | `list` / `create` / `manage` | 标签管理 |
| `ac` | `list` / `add` / `update` / `delete` | 验收标准 |
| `subtasks` | `list` / `add` / `update` / `delete` / `parent` | 子任务管理 |
| `knowledge` | `list` / `create` / `update` / `supersede` | 工作区知识库 |
| `activity` | `activity ` | 任务活动时间线 |
| `docs` | `list` / `get` / `create` / `update` | 项目文档 |
任务 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 ` 将知识条目与具体任务关联（资料来源：[src/cli/commands/knowledge.ts:1-25]()）。活动流命令 `harmony activity ` 通过 `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`，其中 `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` 标志：
```bash
harmony login --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 # 发布里程碑（自动清理非 Done 任务）
```
## 故障排查
- **命令找不到**：命令分组未注册或名称拼写错误，确认使用的是顶级子命令而非已废弃的别名（资料来源：[src/cli/index.ts:8-19]()）。
- **认证失败**：检查 `~/.harmony/config.json` 中 `activeProject` 是否指向仍存在的项目；token 失效时重新执行 `harmony login --token `（资料来源：[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)
---
## MCP 服务器、工具注册表与数据访问层
### 相关页面
相关主题：[项目概述与系统架构](#page-1), [CLI 命令、认证与配置](#page-2), [Claude Code 插件生命周期与工作流技能](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [src/cli/index.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/index.ts)
- [src/cli/commands/auth.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/auth.ts)
- [src/cli/commands/tasks.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/tasks.ts)
- [src/cli/commands/comments.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/comments.ts)
- [src/cli/commands/milestones.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/milestones.ts)
- [src/cli/commands/dependencies.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/dependencies.ts)
- [src/cli/commands/knowledge.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/knowledge.ts)
- [src/cli/commands/acceptance-criteria.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/acceptance-criteria.ts)
- [src/cli/commands/activity.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/activity.ts)
- [src/cli/commands/project.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/project.ts)
- [src/cli/commands/subtasks.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/subtasks.ts)
- [src/cli/config.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/config.ts)
- [commands/harmony-setup.md](https://github.com/ycomplex/harmony-plugin/blob/main/commands/harmony-setup.md)
- [package.json](https://github.com/ycomplex/harmony-plugin/blob/main/package.json)
- [README.md](https://github.com/ycomplex/harmony-plugin/blob/main/README.md)
# MCP 服务器、工具注册表与数据访问层
## 概览
Harmony 插件同时提供 CLI 与 MCP 服务器两个入口，二者共享同一套数据访问工具函数。CLI 使用 Commander.js 解析参数并以 `src/tools/*` 下的纯函数封装对 Supabase 后端的调用；MCP 服务器则基于 `@modelcontextprotocol/sdk` 将同一批工具暴露给 Claude Code 调用。`package.json` 中 `@modelcontextprotocol/sdk` 与 `@supabase/supabase-js` 并列为运行时依赖，佐证了这一双前端、单后端的架构。资料来源：[package.json](https://github.com/ycomplex/harmony-plugin/blob/main/package.json)、[README.md](https://github.com/ycomplex/harmony-plugin/blob/main/README.md)
## 整体架构
```mermaid
graph TB
subgraph "前端入口"
CLI["CLI 进程 (harmony)
Commander.js"]
MCP["MCP Server
@modelcontextprotocol/sdk"]
end
subgraph "工具层 src/tools/*"
T1[tasks]
T2[comments]
T3[milestones]
T4[dependencies]
T5[knowledge]
Tn[acceptance-criteria
subtasks · cycles · epics ...]
end
subgraph "支撑模块"
Auth[auth.ts · HarmonyAuth]
Sup[supabase.ts · createAuthenticatedClient]
Cfg[config.ts · 本地多项目]
RC[run-command.ts · 上下文与错误处理]
end
Backend[(Supabase 后端
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](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/index.ts)
每个子模块遵循统一三段式：
1. **取或建父命令**。`comments` 模块先通过 `program.commands.find((c) => c.name() === 'tasks')` 找到 `tasks` 子命令，找不到则抛错。资料来源：[src/cli/commands/comments.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/comments.ts)
2. **挂载子命令链**。`milestones` 模块自建 `milestones` 父命令，再串联 `list` / `create` / `update` / `ship`，并以 `--shipped` / `--planning` 互斥状态过滤。资料来源：[src/cli/commands/milestones.ts](https://github.com/ycomplex/harmony-plugin/blob/main/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](https://github.com/ycomplex/harmony-plugin/blob/main/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](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/acceptance-criteria.ts)
工具函数签名一致——接收 `(client, projectId, userId?, params)`，返回 `Promise`。`dependencies` 模块的 `list` 动作演示了双侧投影：先取出 `data.depends_on` 与 `data.blocks` 两条关系链，再把每条记录 `map` 成包含 `task_number` / `title` / `status` 的扁平行以适配表格输出。资料来源：[src/cli/commands/dependencies.ts](https://github.com/ycomplex/harmony-plugin/blob/main/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](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/knowledge.ts)
`subtasks` 模块则演示了"父→子"反查：`parent` 子命令调用 `listParent` 返回单条记录（父任务的 `task_number` / `title` / `status`），`add` / `remove` 子命令复用同一 `manageSubtasks` 工具，分别传入 `{ add: children }` 与 `{ remove: children }` 参数。资料来源：[src/cli/commands/subtasks.ts](https://github.com/ycomplex/harmony-plugin/blob/main/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 }`，每条 `ProjectConfig` 至少含 `name` 与 `token`，可附加 `supabaseUrl` / `supabaseAnonKey`。资料来源：[src/cli/config.ts](https://github.com/ycomplex/harmony-plugin/blob/main/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](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/auth.ts)、[src/cli/commands/project.ts](https://github.com/ycomplex/harmony-plugin/blob/main/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](https://github.com/ycomplex/harmony-plugin/blob/main/commands/harmony-setup.md)
## 常见失败模式
| 现象 | 根因 | 处理 |
|------|------|------|
| MCP 工具调用鉴权失败 | MCP 进程启动时未读取到 `HARMONY_API_TOKEN` | 配置 token 后必须 `/exit` 重启 Claude Code |
| 切换项目后仍读到旧数据 | `project switch` 仅改本地配置 | 重启 MCP/CLI 进程以让 `ctx.projectId` 重建 |
| `--json` 不生效 | action 内需 `program.opts().json` 显式读取 | 配合 `formatTable`/`formatDetail` 的 json 模式分支使用 |
| 任务 ID 无法定位 | 工具函数接收字符串，后端承担解析 | 命令行接受 UUID、数字、`B-123` 三种形式 |
| 配置文件泄漏风险 | `config.json` 已是 `0o600` | 检查 `HARMONY_CONFIG_DIR` 指向目录的权限 |
## See Also
- 项目概览与 CLI 命令清单：[README.md](https://github.com/ycomplex/harmony-plugin/blob/main/README.md)
- 插件安装与 token 配置流程：[commands/harmony-setup.md](https://github.com/ycomplex/harmony-plugin/blob/main/commands/harmony-setup.md)
- 本地多项目配置层：[src/cli/config.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/config.ts)
- 认证与登录实现：[src/cli/commands/auth.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/auth.ts)
- CLI 入口与命令注册表：[src/cli/index.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/index.ts)
---
## Claude Code 插件生命周期与工作流技能
### 相关页面
相关主题：[项目概述与系统架构](#page-1), [MCP 服务器、工具注册表与数据访问层](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [.claude-plugin/marketplace.json](https://github.com/ycomplex/harmony-plugin/blob/main/.claude-plugin/marketplace.json)
- [.claude-plugin/plugin.json](https://github.com/ycomplex/harmony-plugin/blob/main/.claude-plugin/plugin.json)
- [hooks/hooks.json](https://github.com/ycomplex/harmony-plugin/blob/main/hooks/hooks.json)
- [.mcp.json](https://github.com/ycomplex/harmony-plugin/blob/main/.mcp.json)
- [commands/harmony-setup.md](https://github.com/ycomplex/harmony-plugin/blob/main/commands/harmony-setup.md)
- [skills/start-work/SKILL.md](https://github.com/ycomplex/harmony-plugin/blob/main/skills/start-work/SKILL.md)
- [README.md](https://github.com/ycomplex/harmony-plugin/blob/main/README.md)
- [package.json](https://github.com/ycomplex/harmony-plugin/blob/main/package.json)
- [src/cli/config.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/config.ts)
- [src/cli/commands/auth.ts](https://github.com/ycomplex/harmony-plugin/blob/main/src/cli/commands/auth.ts)
# Claude Code 插件生命周期与工作流技能
## 插件定位与组成
`harmony-plugin` 仓库同时承载 Harmony 的 CLI 工具与 Claude Code 插件两种形态。当作为 Claude Code 插件安装时，它向宿主注入三类能力：MCP 服务器、工作流技能（workflow skills）以及初始化斜杠命令 [README.md](README.md)。具体而言：
- **MCP 服务器**：以 TypeScript 实现，依赖 `@modelcontextprotocol/sdk` 与 `@supabase/supabase-js`；启用插件后会自动加载，工具名前缀统一为 `mcp__harmony__`（例如 `mcp__harmony__get_task`），覆盖任务、标签、评论、活动、文档、周期、里程碑以及批量操作 [README.md](README.md) [package.json](package.json)。
- **工作流技能**：`start-work` 与 `finish-work`，封装"开工—收尾"回路 [README.md](README.md)。
- **设置命令**：`/harmony-setup`，负责写入 API Token 并验证连通性 [commands/harmony-setup.md](commands/harmony-setup.md)。
MCP 入口在仓库根的 `.mcp.json` 中声明；插件描述与市场清单分别存放在 `.claude-plugin/plugin.json` 与 `.claude-plugin/marketplace.json` 中 [README.md](README.md)。
## 插件生命周期
从安装到可用，插件需依次经历四个阶段，全部在 Claude Code 会话内完成：
```mermaid
flowchart LR
A[添加市场源
/plugin marketplace add] --> B[安装插件
/plugin install]
B --> C[重启 Claude Code]
C --> D[SessionStart Hook
npm install + tsc 构建]
D --> E{dist/index.js
已存在?}
E -- 否 --> F[构建并写入 dist/]
E -- 是 --> G[跳过构建]
F --> H
G --> H[运行 /harmony-setup
写入 HARMONY_API_TOKEN]
H --> I[再次重启
MCP 读取环境变量]
I --> J[就绪：mcp__harmony__* 工具可用]
```
各阶段要点：
1. **市场与安装**
在 Claude Code 内依次执行 `/plugin marketplace add ycomplex/harmony-plugin` 与 `/plugin install harmony-plugin@ycomplex` [README.md](README.md)。
2. **首次构建**
重启后，`SessionStart` 钩子（在 `hooks/hooks.json` 中定义）会自动安装 npm 依赖并编译 TypeScript MCP 服务器，约耗时 10 秒；若 `dist/index.js` 已存在则跳过构建，实现会话级缓存 [README.md](README.md)。
3. **Token 配置**
`/harmony-setup` 命令读取项目根的 `.claude/settings.local.json`，在 `env.HARMONY_API_TOKEN` 字段写入 Token，并通过调用 `mcp__harmony__list_tasks`（`limit=1`）验证连通性；若失败则要求用户检查 Token [commands/harmony-setup.md](commands/harmony-setup.md)。
4. **最终激活**
Token 仅在 Claude Code 进程重启后才会被 MCP 服务器读取，因此配置完成后必须再次 `/exit` 后启动 `claude` [commands/harmony-setup.md](commands/harmony-setup.md)。
CLI 侧走相同的认证通道：`harmony login --token ` 借助 `HarmonyAuth` 解析 Token 并调用 `createAuthenticatedClient` 获取 Supabase 客户端，凭据最终持久化到 `~/.harmony/config.json`（默认权限 `0o600`，目录权限 `0o700`） [src/cli/commands/auth.ts](src/cli/commands/auth.ts) [src/cli/config.ts](src/cli/config.ts)。
## 自动化更新
为获得自动更新能力，可进入 `/plugin` 的 **Marketplaces** 选项卡，选择 **ycomplex** 并启用 auto-update；该机制依赖于 `.claude-plugin/marketplace.json` 中声明的版本字段 [README.md](README.md)。
## 工作流技能
`start-work` 与 `finish-work` 两个技能由独立的 SKILL.md 描述，组合成端到端开发回路：
| 技能 | 触发时机 | 关键动作 |
|------|----------|----------|
| `start-work` | 开启一段任务 | 查找或创建 Harmony 任务 → 状态置为 *In Progress* → 创建隔离的 git worktree → 推荐执行路径 |
| `finish-work` | 任务收尾 | 校验就绪状态 → rebase → squash 合并 → 清理 worktree → 任务状态改为 *Done* |
技能细节见 `skills/start-work/SKILL.md` 等文件；其执行依赖官方 `superpowers` 插件提供的能力 [README.md](README.md)。
## 失败模式与排查
- **构建失败**：首次会话若依赖安装中断，可删除 `dist/index.js` 让 `SessionStart` 钩子强制重建 [README.md](README.md)。
- **Token 未生效**：写完 `settings.local.json` 后忘记再次重启，表现为 MCP 调用返回未鉴权错误；`/harmony-setup` 第 4 步已显式提示 [commands/harmony-setup.md](commands/harmony-setup.md)。
- **Token 泄露**：`/harmony-setup` 强制将 `.claude/settings.local.json` 加入 `.gitignore`；采用手工配置时需自行核对 [commands/harmony-setup.md](commands/harmony-setup.md)。
- **多项目切换**：CLI 与 Claude Code 插件彼此独立；切换项目需使用 `harmony project switch ` 更新 `~/.harmony/config.json` 的 `activeProject` 字段 [src/cli/config.ts](src/cli/config.ts)。
## See Also
- CLI 命令总览与输出模式：[README.md](README.md)
- `/harmony-setup` 步骤定义：[commands/harmony-setup.md](commands/harmony-setup.md)
- 多项目本地配置与文件权限：[src/cli/config.ts](src/cli/config.ts)
- 登录与认证客户端初始化：[src/cli/commands/auth.ts](src/cli/commands/auth.ts)
---
---
## Doramagic 踩坑日志
项目：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