loom-engineering

loom — Weave Specs into Execution

AI 工程化框架。把需求、规范、上下文、执行过程"织"成一套稳定工程流程。

loom 是什么

• 一套 skills + commands + hooks 的集合，注入到 AI 编程工具中
• 一条 按任务类型自适应的开发流水线：根据 feature / bugfix / hotfix / refactor / quickfix / chore / qa / pm-prototype 自动选择对应步骤
• 一个 CLI 工具（loom），负责安装、更新、诊断、卸载，以及流水线执行（run/status/tasks/index）、证据导出（evidence）、结构化记忆（memory）和 MCP server（mcp-serve）
• 一个 项目初始化器（/loom-init-project 或 loom init-project），自动扫描项目生成宪章、结构化记忆和 agent 入口

从需求描述出发，经过头脑风暴、计划拆解、隔离开发、代码审查，最终交付。

支持工具矩阵

工具	支持等级	入口文件	Skills	Hooks	Plugin	MCP 配置
Claude Code	full	CLAUDE.md	✅	✅	✅	✅
Codex	full	AGENTS.md	✅	✗	✗	✅
Cursor	full	.cursor/rules/*.mdc	✅	✗	✗	✅
GitHub Copilot	full	.github/copilot-instructions.md	✅	✗	✗	✗
OpenCode	full	AGENTS.md	✅	✅	✅	✅

• full：完整支持，适配器已实现
• Hooks：当前完整 hook 运行时主要由 Claude Code 插件接入；OpenCode 适配器已注册插件和 MCP，但 config/tools.schema.json 中仍标记 hooksSupport: false，后续生命周期扩展见 docs/evolution-roadmap.md
• 适配器契约：工具能力、安装范围、配置面、loom-managed 产物和版本探测方式以 config/tools.schema.json 的 contract 为单一源，并生成到 src/generated/tooling.js 的 ADAPTER_CONTRACTS；loom doctor 会基于契约输出一致性和版本诊断

安装

前置条件

• Node.js >= 22
• （可选）codegraph — 装了则 loom index 自动委派给它做 AST 级图索引，并注册其 MCP server；未装则跳过图查询能力

方式一：一键安装脚本

git clone https://github.com/xiqin/loom.git
cd loom
bash install.sh --tool claude-code

远程一键安装：

# Unix
curl -fsSL https://raw.githubusercontent.com/xiqin/loom/main/install.sh | bash -s -- --tool claude-code

# Windows PowerShell
irm https://raw.githubusercontent.com/xiqin/loom/main/install.ps1 -OutFile install.ps1; .\install.ps1 -Tool claude-code

方式二：npm 安装

npm i -g loom-engineering
loom install --tool claude-code

安装选项

Flag	作用
--tool <targets>	目标工具（必填，逗号分隔或 "all"）
--dry-run	预览，不实际写入
--from-release	从 GitHub release tag 下载（可重现安装）
--version <ver>	指定下载版本（配合 --from-release）

安装后验证

loom doctor    # 诊断安装状态
loom list      # 列出可用 skills 和 commands

MCP 性能开关

loom 的 MCP server 支持通过环境变量控制工具暴露和运行统计。需要把变量配置到客户端启动 loom mcp-serve 的 MCP server 配置里，而不是只在普通 shell 会话里临时设置。

变量	建议值	作用
LOOM_LAZY_TOOLS	1	启用 MCP 工具懒加载，默认只暴露基础工具，按需加载 pipeline/context/memory/session 工具组，减少工具定义带来的上下文开销。
LOOM_TELEMETRY	1	开启 loom MCP 工具调用统计，记录调用次数、耗时、响应字节数和估算响应 token；可通过 loom_telemetry 工具查看，MCP server 退出时也会向 stderr 输出摘要。

配置示例：

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "loom": {
      "command": "loom",
      "args": ["mcp-serve"],
      "env": {
        "LOOM_LAZY_TOOLS": "1",
        "LOOM_TELEMETRY": "1",
      },
    },
  },
}

// OpenCode: mcp.loom.environment
{
  "mcp": {
    "loom": {
      "type": "local",
      "command": ["loom", "mcp-serve"],
      "enabled": true,
      "environment": {
        "LOOM_LAZY_TOOLS": "1",
        "LOOM_TELEMETRY": "1",
      },
    },
  },
}

修改 MCP 配置后需要重启对应客户端，运行中的 MCP server 不会自动继承新环境变量。

初始化项目上下文

在 Codex/Claude/OpenCode 中直接触发 loom-init-project skill 即可；脚本由 skill 自动运行，不需要用户手动调用。

也可以使用 CLI：

loom init-project

卸载

卸载

# 脚本卸载
bash uninstall.sh --tool claude-code
.\uninstall.ps1 -Tool claude-code

# CLI 卸载
loom uninstall --tool claude-code

卸载只清理用户级安装的文件（用户目录下的 skills、commands、plugin 注册），不碰项目目录中的任何文件。

恢复

如果误卸载，重新安装即可：

loom install --tool claude-code

版本与发布策略

• 遵循 Semantic Versioning
• 版本号在 package.json 中定义，通过 scripts/sync-version.mjs 同步到所有元数据文件
• 每个生成的文件包含 loom:version=x.y.z 标记，用于检测已安装版本
• loom update 自动比较版本号，仅在版本不同时更新
• loom doctor 显示当前安装状态和版本

版本检查

loom doctor
# 输出示例：
#   Tool: claude-code
#   Version: 2.0.1
#   Status: installed

流水线

流水线由 .loom/workflow.yaml 集中定义。支持两种模式：