Tackle Harness

基于插件的 AI Agent 工作流框架，为 Claude Code 提供任务管理、工作流编排、角色管理等能力

English

为什么选择 Tackle Harness

你告诉 AI 需求，Tackle Harness 帮你管好整个流程：

• 方案先行，人工把关 — AI 先输出实施方案和工作包拆分，等你确认后才动手写代码。不会出现「AI 自作主张改了一堆东西」的情况。
• 复杂需求，并行交付 — 大需求自动拆成多个独立模块，调度多个 Agent 同时工作。前后端、数据库变更同步推进，不用串行等待。
• 经验沉淀，越用越好 — 每次任务完成后自动提炼经验教训。下次遇到类似问题时，Agent 会参考历史经验做出更好的决策。

端到端数据流

用户需求经五个阶段完成从规划到交付的完整生命周期：

flowchart LR
    REQ["用户需求<br/>(自然语言)"]
    P0["P0: 规划<br/>task-creator / split-wp"]
    P1["P1: 审核<br/>human-checkpoint"]
    P2["P2: 执行<br/>agent-dispatcher"]
    P3["P3: 检查<br/>checklist / experience-logger"]
    P4["P4: 汇报<br/>completion-report"]

    O1["docs/wp/*.md<br/>task.md 更新"]
    O2["用户确认/修改<br/>(人工介入)"]
    O3["Agent Teams<br/>(多代理并行)"]
    O4["完成报告<br/>经验沉淀"]

    REQ --> P0 --> P1 --> P2 --> P3 --> P4

    P0 -.-> O1
    P1 -.-> O2
    P2 -.-> O3
    P3 -.-> O4

安装

推荐方式：全局安装

npm install -g tackle-harness

全局安装后可在任意项目使用 tackle-harness 命令，无需重复安装。

备选方式：本地安装

npm install tackle-harness

本地安装需要使用 npx tackle-harness 或添加到 package.json scripts。

快速开始

# 进入你的项目目录
cd your-project

# 一键初始化（创建配置目录 + 注册钩子）
tackle-harness init

# 迁移旧项目（如之前使用过本地安装）
tackle-harness migrate

# 手动更新配置（当 .claude/settings.json 变更时）
tackle-harness build

注意：全局安装模式下，技能和钩子由 npm 全局管理，项目不再需要本地的 .claude/skills/ 和 .claude/hooks/ 目录。项目只需保留配置文件（.claude/config/ 和 .claude/settings.json）。

使用场景

• 新功能开发 — 需求分析 → 拆分工作包 → 并行开发 → 质量检查
• Bug 批量修复 — 依赖分析 → 并行修复 → 自动验证
• 系统重构 — 架构分析 → 分批执行 → 经验沉淀
• 代码审查 — 质量检查 → 文档同步 → 经验记录
• 项目收尾 — 进度汇总 → 经验沉淀 → 完成报告

完整的场景流程图和操作步骤请参阅 日常工作流最佳实践

命令一览

| 命令 | 说明 | |------|------| | tackle-harness | 默认执行 build | | tackle-harness build | 更新 .claude/settings.json，注册全局技能和钩子 | | tackle-harness validate | 验证插件格式是否正确 | | tackle-harness validate-config | 验证 harness-config.yaml | | tackle-harness init | 首次安装：创建配置目录并注册钩子 | | tackle-harness migrate | 迁移旧项目：删除本地 skills/hooks 目录，更新配置 | | tackle-harness interactive | 交互式插件管理（别名：i） | | tackle-harness status | 显示构建状态和插件统计信息 | | tackle-harness config | 显示/验证当前配置 | | tackle-harness list | 列出所有已注册的插件 | | tackle-harness version | 显示版本信息 | | tackle-harness --root <path> | 指定目标项目路径（默认为当前目录） |

本地安装备注：如果使用 npm install tackle-harness（非全局安装），请在命令前加 npx，例如 npx tackle-harness init。

技能清单

| 技能 | 触发方式 | 功能 | |------|----------|------| | task-creator | "创建任务" / "create task" | 创建单个任务到任务列表 | | batch-task-creator | "批量创建任务" / "batch create tasks" | 批量创建多个任务 | | split-work-package | "拆分工作包" / "split work package" | 将需求拆分为可执行的工作包 | | progress-tracker | "记录进度" / "record progress" | 追踪和汇报工作进度 | | team-cleanup | "清理团队" / "cleanup team" | 释放残留的团队资源 | | human-checkpoint | "等待审核" / "wait for review" | 暂停并请求人工确认 | | role-manager | "查看角色" / "view roles" | 管理项目角色定义 | | checklist | "运行检查" / "run checklist" | 执行检查清单 | | completion-report | "完成报告" / "completion report" | 生成完成报告 | | experience-logger | "总结经验" / "log experience" | 记录项目经验教训 | | watchdog-manager | "启动守护进程" / "start watchdog" | 启动和管理后台守护进程 | | task-archive | "任务归档" / "archive tasks" | 归档已完成工作包 | | tackle-sync | "配置tackle" / "sync" / "初始化" | 自动检测项目状态，执行初始化/更新/迁移 | | agent-dispatcher | "批量执行" / "dispatch agents" | 调度多个子代理并行工作 | | workflow-orchestrator | "开始工作流" / "start workflow" | 编排完整工作流 |

工作流概览

用户需求经过 5 个阶段完成从规划到交付：

需求 → 规划(P0) → 审核(P1) → 执行(P2) → 检查(P3) → 汇报(P4) → 交付

| 阶段 | 做什么 | 关键技能 | |------|--------|----------| | P0 规划 | 解析需求，拆分为工作包，写入文档 | task-creator, split-work-package | | P1 审核 | 暂停等待你确认方案（强制人工介入） | human-checkpoint | | P2 执行 | 多 Agent 并行开发，按依赖调度 | agent-dispatcher | | P3 检查 | 代码/测试/文档质量验证，提炼经验 | checklist, experience-logger | | P4 汇报 | 生成完成报告，询问下一步 | completion-report |

完整的数据流图和阶段细节请参阅 docs/ai_workflow.md

插件架构

Tackle Harness 包含四类插件，共 23 个：

| 类型 | 数量 | 作用 | |------|------|------| | Skill | 15 | 可执行技能，Claude Code 直接调用 | | Provider | 4 | 状态存储、角色注册、记忆存储、守护进程 | | Hook | 2 | 技能门控 + 会话启动时注入 plan-mode 规则 | | Validator | 2 | 文档同步验证、工作包验证 |

插件依赖关系和开发指南请参阅 docs/plugin-development.md

构建后的项目结构

全局安装模式（推荐）

执行 tackle-harness init 后，你的项目中会生成以下内容：

your-project/
  .claude/
    config/
      harness-config.yaml            # 配置文件（可选）
    settings.json                    # 自动注册的 hooks

技能和钩子由全局安装管理，不需要本地的 skills/ 和 hooks/ 目录。

本地安装模式（备选）

如果使用 npm install tackle-harness（非全局安装），执行 tackle-harness build 后会生成：

your-project/
  .claude/
    skills/                          # 15 个技能
      skill-task-creator/skill.md
      ...
    hooks/                           # 2 个 hook
      hook-skill-gate/index.js
      hook-session-start/index.js
    settings.json                    # 自动注册的 hooks

常见问题

安装后技能没有生效？

全局安装模式：

1. 确认已全局安装：npm list -g tackle-harness
2. 执行 tackle-harness init 初始化项目
3. 检查 .claude/settings.json 是否包含 tackle-harness 的 hooks

本地安装模式：

1. 确认在项目根目录执行了 npx tackle-harness build
2. 检查 .claude/skills/ 目录下是否有技能文件夹

多个项目能否共用？

全局安装后，所有项目共用同一套技能和钩子。每个项目只需要自己的配置文件（.claude/config/ 和 .claude/settings.json）。

如何从旧版本迁移？

如果之前使用本地安装模式，迁移到全局安装：

# 1. 全局安装
npm install -g tackle-harness

# 2. 进入项目目录
cd your-project

# 3. 执行迁移命令
tackle-harness migrate

迁移命令会：

• 删除本地的 .claude/skills/ 和 .claude/hooks/ 目录
• 更新 .claude/settings.json 指向全局路径
• 保留你的配置文件（harness-config.yaml）

Windows 路径问题？

全局安装支持 Windows 路径（如 D:\path\to\project），使用正斜杠或反斜杠均可：

tackle-harness build --root D:/path/to/project
tackle-harness build --root D:\path\to\project

如何卸载？

# 卸载全局安装
npm uninstall -g tackle-harness

# 卸载本地安装
npm uninstall tackle-harness

配置文件会保留在 .claude/ 目录中，如需清理请手动删除。

settings.json 中的 hooks 是什么？

tackle-harness build 会自动向 .claude/settings.json 注入三个 hook：

• SessionStart — 会话启动时扫描 plan-mode 技能，将优先级规则注入 system-reminder，确保任务创建类技能强制进入 Plan 模式
• PreToolUse(Edit|Write) — 在特定状态下阻止文件编辑
• PostToolUse(Skill) — 技能调用后更新状态

这些 hook 指向全局安装路径或 node_modules/tackle-harness/ 中的脚本。已有的 settings.json 内容会被保留，仅追加 tackle-harness 相关的 hooks。

如何使用交互式模式？

tackle-harness interactive
# 或使用别名
tackle-harness i

交互式模式提供可视化的插件管理界面，支持：

• 查看所有已注册插件的状态
• 启用/停用插件
• 查看插件依赖关系
• 执行插件验证

本地安装模式下请使用 npx tackle-harness interactive。

CI/CD 如何集成？

在 CI 环境中使用 Tackle Harness：

# 方式 1：全局安装（推荐）
- name: Setup Tackle Harness
  run: |
    npm install -g tackle-harness
    tackle-harness init --root $GITHUB_WORKSPACE

# 方式 2：本地安装
- name: Setup Tackle Harness
  run: |
    npm install tackle-harness
    npx tackle-harness init --root $GITHUB_WORKSPACE

项目已配置 GitHub Actions 工作流，提交 PR 或推送代码会自动运行测试。

文档

• 日常工作流最佳实践 - 按场景的使用手册和 Skill 速查
• 配置参考 - 完整的配置文件说明
• 插件开发 - 插件架构和开发指南
• 工作流详解 - 完整的工作流数据流和阶段说明

示例项目

查看 examples/ 目录获取完整的示例项目：

• minimal — 最小示例项目，展示基本集成方式和配置

持续集成

项目使用 GitHub Actions 进行 CI/CD：

• CI 工作流 — 在 Node.js 18 和 20 上运行测试矩阵
• 发布工作流 — Tag 触发自动发布到 npm

详见 .github/workflows/

贡献

欢迎贡献！我们接受 Bug 报告、功能建议、代码提交和文档改进。详见 贡献指南。

快速上手：Fork → 创建分支 → 修改 → 提交 PR。Commit 遵循 Conventional Commits 格式。

许可证

MIT License - 详见 LICENSE 文件

致谢

本项目借鉴了以下开源项目的优秀设计：

• DeerFlow - 记忆提取和插件架构