{"_id":"@can1177/sloom","name":"@can1177/sloom","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@can1177/sloom","version":"0.1.0","description":"sLoom: open-source Skill-first orchestrator CLI for weaving engineering Skills into executable workflows.","type":"module","packageManager":"pnpm@9.6.0","scripts":{"sloom":"node packages/cli/bin/sloom.js","test":"node --test","check":"node packages/cli/bin/sloom.js --help && node packages/cli/bin/sloom.js scan examples/skills --out .sloom/inventory.json && node packages/cli/bin/sloom.js propose --from .sloom/inventory.json --out .sloom/proposals/overlays.json && node packages/cli/bin/sloom.js validate examples/bugfix.plan.json && node packages/cli/bin/sloom.js graph examples/bugfix.plan.json && node packages/cli/bin/sloom.js run examples/bugfix.plan.json --dry-run && node packages/cli/bin/sloom.js eval evals/development-flow.json && node packages/cli/bin/sloom.js runs --json"},"workspaces":["packages/*"],"engines":{"node":">=22"},"keywords":["agents","skills","orchestration","cli","workflow","developer-tools"],"license":"MIT","bin":{"sloom":"packages/cli/bin/sloom.js"},"repository":{"type":"git","url":"git+https://github.com/CAN1177/skill-loom.git"},"homepage":"https://github.com/CAN1177/skill-loom#readme","bugs":{"url":"https://github.com/CAN1177/skill-loom/issues"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_id":"@can1177/sloom@0.1.0","gitHead":"04ca0899e7e4e502d0475387505863c436fcd372","_nodeVersion":"22.23.1","_npmVersion":"10.9.8","dist":{"integrity":"sha512-+TlVNlA74Db1SN8rVSJhYerffkGDlLHrtt5A86It2jn3Y6kkjOUC0hsfF9a3KZfqXXbnlNFnPQyRfCMeF0LoYQ==","shasum":"a2c87db4c814ac1487cfaf37eee27bc64eee3fa0","tarball":"https://registry.npmjs.org/@can1177/sloom/-/sloom-0.1.0.tgz","fileCount":35,"unpackedSize":166099,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCmZH0cZSjWMRU9KzAFwfyafZ+OId5hA7ipqqNiY66HigIgV2BW2TN9SDi3X55hRaEOxUO8PuwCrdASPqQjF3+eoQY="}]},"_npmUser":{"name":"self-improvement","email":"yican1175@163.com"},"directories":{},"maintainers":[{"name":"self-improvement","email":"yican1175@163.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sloom_0.1.0_1784645498073_0.6626384110106105"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-21T14:51:37.903Z","0.1.0":"2026-07-21T14:51:38.217Z","modified":"2026-07-21T14:51:38.456Z"},"maintainers":[{"name":"self-improvement","email":"yican1175@163.com"}],"description":"sLoom: open-source Skill-first orchestrator CLI for weaving engineering Skills into executable workflows.","homepage":"https://github.com/CAN1177/skill-loom#readme","keywords":["agents","skills","orchestration","cli","workflow","developer-tools"],"repository":{"type":"git","url":"git+https://github.com/CAN1177/skill-loom.git"},"bugs":{"url":"https://github.com/CAN1177/skill-loom/issues"},"license":"MIT","readme":"<p align=\"center\">\n  <img src=\"docs/assets/sloom-icon.svg\" alt=\"sLoom sL monogram logo\" width=\"96\" height=\"96\">\n</p>\n\n<h1 align=\"center\">sLoom</h1>\n\n**sLoom**（`sloom`）是一个**开源**的 Skill-first Orchestrator CLI，用来把分散的工程 `SKILL.md` 文件编织成可路由、可审查、可执行的研发工作流。\n\n[English README](README.md)\n\n## 图标含义\n\n**Skill Loom** 的含义是：将离散的研发 Skills 按依赖、阶段、权限和质量门“编织”为可执行工作流。`sL` 字母图标和项目名直接呼应：`s` 代表 Skill，`L` 代表 Loom；穿过字母的编织线代表工作流编排，右下角的勾选标记代表可审查的质量门。\n\n它的核心思路很简单：\n\n> **Skill 是第一抽象。** Claude Code、Codex、Shell、多 Agent runtime 都只是执行后端，不应该成为工作流策略本身。\n\n```text\n任务 / Issue\n  -> Skill Catalog\n  -> Router\n  -> Blueprint Planner\n  -> DAG Validator\n  -> Deterministic Executor\n  -> Artifacts + Gates + Trace\n```\n\n## 为什么做 sLoom？\n\n很多团队已经沉淀了大量好用的研发 Skills：需求分析、仓库探索、实现、测试、Review、发布检查等。但这些 Skills 往往分散在不同目录、不同工具和不同使用习惯里。\n\n对于一个简单开发任务，我们仍然需要人工判断：\n\n- 先做仓库探索，还是先澄清需求？\n- 什么情况下需要设计评审？\n- 实现、测试、Review 应该分别由哪个 Skill 完成？\n- 节点之间靠什么交接？聊天历史，还是可验证产物？\n- 哪些步骤需要审批，哪些命令应该禁止？\n\nsLoom 的目标不是再造一个“大而全 Agent”，而是把这些已有 Skills 治理起来，让它们可以被稳定选择、组合和执行。\n\n## 当前状态\n\n这个仓库目前是第一个开源 MVP scaffold，已经包含：\n\n- 零依赖 Node.js 22 CLI\n- `SKILL.md` + 非侵入式 metadata overlay 本地索引器\n- Catalog linter\n- 带 Pack 过滤的 lexical router\n- bugfix / feature Blueprints\n- Artifact DAG planner\n- Plan validator\n- Mermaid graph 输出\n- dry-run trace writer\n- 可恢复的 Workflow Artifact Runtime\n- safe shell executor 和 agent handoff runtime\n- Codex / Claude Code / CAO dispatch packages\n- 示例 Skills、Pack、Blueprint 和 WorkflowPlan\n\nSQLite/FTS、LLM rerank、显式 opt-in 的真实子进程执行、worktree 隔离、更完整的 CAO log 回收和 Gate 强制执行是后续里程碑。\n\n## 快速开始\n\n### 优先使用 npm package\n\n需要 Node.js 22+。可以全局安装 CLI，也可以直接用 `npx` 运行：\n\n```bash\nnpm install -g sloom\nsloom --help\n\n# 或者不全局安装\nnpx sloom --help\n```\n\n创建一个本地 sLoom 工作区，并先体验 npm 包内置的示例 Skills：\n\n```bash\nmkdir sloom-demo && cd sloom-demo\nsloom init\nsloom index\nsloom skills list\n\nsloom route \"修复资源列表搜索为空时报错\" --json\nsloom plan --task \"修复资源列表搜索为空时报错\" --blueprint bugfix --out .sloom/plans/search-empty-bug.json\nsloom validate .sloom/plans/search-empty-bug.json\nsloom graph .sloom/plans/search-empty-bug.json\nsloom run .sloom/plans/search-empty-bug.json --executor auto --max-nodes 2\nsloom runs\n```\n\n接入你自己的 Skills 时，显式传入本地 Skill 目录：\n\n```bash\nsloom scan ~/.agents/skills ~/.codex/skills --out .sloom/inventory.json\nsloom propose --from .sloom/inventory.json --out .sloom/proposals/overlays.json\nsloom apply .sloom/proposals/overlays.json --yes --backup\nsloom index ~/.agents/skills ~/.codex/skills\nsloom route \"实现一个小 bugfix 并跑回归测试\"\n```\n\n使用包内置 golden dataset 验证 routing / planning 质量：\n\n```bash\nsloom eval\nsloom eval --json --out .sloom/reports/development-flow.json\n```\n\n### 从源码开发\n\n如果你在本仓库内开发，也可以不安装 npm package，直接运行源码 CLI：\n\n```bash\nnode packages/cli/bin/sloom.js --help\nnode packages/cli/bin/sloom.js index examples/skills\nnode packages/cli/bin/sloom.js eval evals/development-flow.json\n```\n\n## Workflow 执行与 Artifact\n\n`sloom run` 会在 `.sloom/runs/<run-id>` 下创建可恢复的运行目录：\n\n```text\n.sloom/runs/<run-id>/\n  plan.lock.json\n  run-state.json\n  events.jsonl\n  artifacts/\n    manifest.json\n    <node-id>/<artifact-name>.md\n```\n\n\nP3/P4 run 目录还可能包含 agent handoff 和 dispatch package：\n\n```text\n.sloom/runs/<run-id>/\n  handoffs/<node-id>/\n    task.md\n    inputs.json\n    expected-outputs.json\n  dispatches/<node-id>/<adapter>/\n    prompt.md\n    dispatch.json\n    status.json\n    launch-cao.sh        # 仅 CAO\n```\n\n这让 sLoom 现在就能在 Claude CLI 或 Codex CLI 中使用：sLoom 负责 routing、plan lock、policy、state、events 和 artifacts；外层 Agent 执行 handoff task，并把结果提交回运行时。更多说明见 [Agent Integration](docs/agent-integration.md) 和可选的 [sLoom Entry Skill](skills/sloom-orchestrator/SKILL.md)。\n\n当前默认 local runtime 是确定性、安全的：不会修改源码，只会把每个节点的输出物化为可追踪 Artifact，便于检查和恢复。\n\nP3 增加了显式 Executor Adapter 模式。`--executor auto` 会对 policy 允许的 shell 节点执行小范围 safe-command allowlist；对 Codex / Claude Code 节点则生成可持久化的 handoff package，而不是偷偷启动 Agent 或直接改源码。P4 进一步提供 provider dispatch package：`--executor codex`、`--executor claude-code`、`--executor cao` 会生成可审计的 prompt/spec，其中 CAO 的 `allowedTools` 会从 sLoom policy 映射而来。真实 Agent 完成任务后写出 Markdown Artifact，通过 `sloom artifact put` 回填，再用 `sloom resume --executor auto|cao` 继续 DAG。\n\n常用命令：\n\n```bash\nnode packages/cli/bin/sloom.js executors\nnode packages/cli/bin/sloom.js run .sloom/plans/search-empty-bug.json --max-nodes 2\nnode packages/cli/bin/sloom.js run .sloom/plans/search-empty-bug.json --executor auto\nnode packages/cli/bin/sloom.js run .sloom/plans/search-empty-bug.json --executor cao\nsh .sloom/runs/<run-id>/dispatches/<node-id>/cao/launch-cao.sh\nnode packages/cli/bin/sloom.js artifact put <run-id> analysis requirement.spec ./requirement.spec.md --executor cao\nnode packages/cli/bin/sloom.js resume <run-id> --executor cao\nnode packages/cli/bin/sloom.js runs --json\n```\n\n\n## 质量评估\n\nP5 增加了轻量评估闭环，用来证明 sLoom 不是“炫技编排”，而是真的在降低研发摩擦：\n\n```bash\nnode packages/cli/bin/sloom.js eval evals/development-flow.json\n```\n\n报告会检查 route top-3 recall、plan Skill recall、期望 Artifact 覆盖率、预估人工介入次数和 prompt pollution reduction。团队演示脚本和落地清单见 [Team Adoption Guide](docs/guides/team-adoption.md)。\n\n## 仓库结构\n\n```text\npackages/\n  core/              catalog、routing、planning、validation、graph utilities\n  cli/               CLI 入口\nblueprints/          bugfix、feature 等工作流骨架\npacks/               面向场景的 Skill 集合和路由策略\nschemas/             metadata overlay 和 plan 的 JSON Schemas\nexamples/            示例 Skills 和 Plans\ndocs/                架构说明、Agent 集成说明、团队推广指南和路线图\nevals/               route/plan 质量评估 golden datasets\nscripts/demo/        可复现演示脚本\nskills/              可选的 sLoom Entry Skill，用于 Agent 自然语言调用\n```\n\n## Skill metadata overlay\n\nsLoom 默认不应该修改你已有的本地 Skill。`scan -> propose -> apply --backup` 让每一次元数据变更都可审查、可回滚。`SKILL.md` 目录应被视为只读资产，编排元数据放在 sLoom 工作区或 Pack 中：\n\n```text\n# 已存在的 Skill，只读\n~/.claude/skills/my-skill/\n  SKILL.md\n\n# sLoom 管理的项目级编排元数据\n.sloom/overlays/skills/implementation.targeted-fix.json\n\n# 或团队/开源共享 Pack 中的 overlay\npacks/frontend-delivery/skills/implementation.targeted-fix.json\n```\n\n同目录 `sloom.json` 仍然可以支持，但它只适合 Skill 作者主动随 Skill 发布便携元数据的场景；不应该作为治理既有本地 Skill 的默认方式。\n\n一个最小 overlay 示例：\n\n```json\n{\n  \"apiVersion\": \"sloom.dev/v1alpha1\",\n  \"kind\": \"SkillOverlay\",\n  \"metadata\": {\n    \"id\": \"implementation.targeted-fix\",\n    \"version\": \"1.0.0\",\n    \"title\": \"Targeted Fix Implementation\",\n    \"source\": {\n      \"type\": \"local-skill\",\n      \"path\": \"examples/skills/targeted-fix\",\n      \"fingerprint\": \"sha256:...\"\n    }\n  },\n  \"spec\": {\n    \"intents\": [\"bugfix\", \"feature\"],\n    \"capabilities\": [\"implementation\", \"small-change\"],\n    \"inputs\": { \"required\": [\"repo.context\"], \"optional\": [\"requirement.spec\"] },\n    \"outputs\": [\"source.diff\", \"implementation.summary\"],\n    \"execution\": { \"preferredExecutor\": \"claude-code\", \"workspace\": \"isolated-worktree\", \"timeoutMinutes\": 40 },\n    \"policy\": { \"risk\": \"medium\", \"permissions\": [\"filesystem.write\", \"git.diff\"], \"denyCommands\": [\"rm -rf\", \"git push\"] },\n    \"routing\": { \"includeKeywords\": [\"修复\", \"bug\", \"实现\"], \"tags\": [\"implementation\"] }\n  }\n}\n```\n\noverlay 描述的是：这个 Skill 适合什么任务、需要什么输入、会产出什么 Artifact、应该用哪个执行器、有哪些权限边界和质量门。\n\n## 设计原则\n\n1. **Artifact-first**：节点之间传递具名 Artifact，而不是隐藏的聊天历史。\n2. **Plan before run**：先冻结并校验 DAG，再执行。\n3. **Minimal closed DAG**：只选择满足 Artifact 依赖所需的最小 Skill 集合。\n4. **Policy as code**：权限、命令 deny-list、Gate 和审批点必须能在 prompt 之外被执行和校验。\n5. **Executors are adapters**：Claude Code、Codex、Shell、CAO 负责执行已规划节点，不负责最终 Skill 选择。\n\n## 适合谁使用？\n\nsLoom 适合这些团队：\n\n- 已经有一批内部 `SKILL.md`，但缺少统一治理和自动编排；\n- 希望把研发流程从 prompt 经验升级为 Artifact 契约和 Workflow DAG；\n- 想让 Claude Code、Codex、Shell、多 Agent runtime 各司其职；\n- 不希望把 Skill 选择、质量门和权限策略完全交给某个 Supervisor 临场决定。\n\n## 当前 MVP 能验证什么？\n\n当前版本不是最终形态，但已经足够验证一个关键假设：\n\n> 现有 Skills 是否能够被稳定描述为 Artifact producer / consumer，并自动组合成最小可执行工作流。\n\n如果这个假设成立，后续再接入 SQLite/FTS、LLM rerank、真实 executor、worktree 隔离、失败恢复和多 Agent 并行，都会有更稳的基础。\n\n## 架构分层\n\nsLoom 会刻意保持分层：\n\n```text\nsLoom Core\n  = Skill Catalog + Pack + Router + Blueprint Planner\n  + Artifact DAG Validator + Policy + Trace\n\nExecution Runtime\n  = Shell / Claude Code / Codex / CAO\n```\n\nSkill 选择、计划生成、权限策略和质量门属于 sLoom Core；执行器只负责运行已经冻结的节点。这样做的好处是：计划可以被审查，失败可以被恢复，风险可以被控制，团队也能持续优化路由和规划质量。\n\n## Roadmap\n\n完整计划见 [`docs/roadmap.md`](docs/roadmap.md)。下一阶段重点：\n\n- 用 SQLite + FTS5 替换 JSON Catalog\n- 增强 schema validation\n- 支持 plans 和 metadata overlays 的 YAML round-trip\n- 增加 Codex、Claude Code、CAO 的显式 opt-in 子进程/会话监控\n- 增加 git worktree 隔离\n- 用真实团队任务扩充 routing / planning eval datasets\n\n## License\n\nMIT\n","readmeFilename":"README.zh-CN.md","_rev":"1-293f73a34ced02102181d84e309cf25f"}