{"_id":"@atom-workflow-agent/select-atom","name":"@atom-workflow-agent/select-atom","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@atom-workflow-agent/select-atom","version":"1.0.0","description":"Built-in deterministic and human-in-the-loop selection atoms.","license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/joekbits/atom-workflow-agent.git","directory":"atoms/select-atom"},"homepage":"https://github.com/joekbits/atom-workflow-agent/tree/main/atoms/select-atom#readme","bugs":{"url":"https://github.com/joekbits/atom-workflow-agent/issues"},"keywords":["atom","workflow","decision","selector"],"type":"module","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"publishConfig":{"access":"public","provenance":true},"engines":{"node":">=22"},"dependencies":{"@atom-workflow-agent/contracts":"0.1.0","@atom-workflow-agent/atom-sdk":"0.1.0"},"scripts":{"build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit","test":"vitest run"},"_id":"@atom-workflow-agent/select-atom@1.0.0","_integrity":"sha512-nw6EiyO5Fb+7svSZD3OjNRWEYnc2TBKsmJmdb9N9rGKQ1PstO8p9QTXei1JFrtZcHkhDa5i3ZKoi1GzPtjpgZw==","_resolved":"/private/tmp/atomflow-npm-release-20260902-1720/atom-workflow-agent-select-atom-1.0.0.tgz","_from":"file:/private/tmp/atomflow-npm-release-20260902-1720/atom-workflow-agent-select-atom-1.0.0.tgz","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-nw6EiyO5Fb+7svSZD3OjNRWEYnc2TBKsmJmdb9N9rGKQ1PstO8p9QTXei1JFrtZcHkhDa5i3ZKoi1GzPtjpgZw==","shasum":"49e0695645d7c73cabd27b677bbe9d533dd19ac4","tarball":"https://registry.npmjs.org/@atom-workflow-agent/select-atom/-/select-atom-1.0.0.tgz","fileCount":28,"unpackedSize":64248,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIH2vEK0ywb+Td1zeE5NnV1ZY108+Myu7iMVAA3wKcmgMAiEAkFGCbnm/bBgnQfi23c81zUyckEu/sGilUMCWKS77NRk="}]},"_npmUser":{"name":"joekbits","email":"wangfeihong868@foxmail.com"},"directories":{},"maintainers":[{"name":"joekbits","email":"wangfeihong868@foxmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/select-atom_1.0.0_1788342343964_0.06568798153023869"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-02T09:45:43.827Z","1.0.0":"2026-09-02T09:45:44.096Z","modified":"2026-09-02T09:45:45.130Z"},"maintainers":[{"name":"joekbits","email":"wangfeihong868@foxmail.com"}],"description":"Built-in deterministic and human-in-the-loop selection atoms.","homepage":"https://github.com/joekbits/atom-workflow-agent/tree/main/atoms/select-atom#readme","keywords":["atom","workflow","decision","selector"],"repository":{"type":"git","url":"git+https://github.com/joekbits/atom-workflow-agent.git","directory":"atoms/select-atom"},"bugs":{"url":"https://github.com/joekbits/atom-workflow-agent/issues"},"license":"Apache-2.0","readme":"# `@atom-workflow-agent/select-atom`\n\n[English](README.md) | [简体中文](README.zh-CN.md)\n\n内置选择器只负责一件事：为 Workflow `DecisionNode` 选择一个静态声明的分支。\n\n## 如何选择 Atom\n\n| Atom | 适用场景 | 是否可能暂停 |\n| --- | --- | --- |\n| `select.rule@1.0.0` | 可以通过有序规则判断结构化事实，并可在必要时让用户选择 | `manual`，或 `auto_then_user` 无匹配/多匹配时 |\n| `select.host-model@1.0.0` | 当前 Codex/Trae 对话需要结合项目或会话上下文判断 | 始终以 HostTask 暂停 |\n\n两者都会返回可审计的 `branch`、`source`、`reason`、`matchedRuleIds` 和 `factsHash`，不会返回目标节点 ID。Compiler 会验证所有可能分支都已由外层 Decision 节点声明。\n\n## 规则选择器\n\n模式：\n\n- `automatic`：选择第一条命中规则，其次使用 `fallbackBranch`，否则失败；\n- `manual`：始终询问用户；\n- `auto_then_user`：仅在恰好一条规则命中时自动选择，否则询问用户。\n\n规则按顺序求值，一条规则可以用 `all` 或 `any` 组合条件。支持 `eq`、`ne`、`gt`、`gte`、`lt`、`lte`、`in`、`not_in`、`contains`、`exists`；`path` 支持 JSON Pointer 或点路径。\n\nDecision Atom 输入示例：\n\n```json\n{\n  \"mode\": \"automatic\",\n  \"facts\": { \"metrics\": { \"lcpMs\": 3200 } },\n  \"rules\": [\n    {\n      \"id\": \"slow-lcp\",\n      \"branch\": \"optimize\",\n      \"match\": \"all\",\n      \"conditions\": [\n        { \"path\": \"/metrics/lcpMs\", \"operator\": \"gt\", \"value\": 2500 }\n      ],\n      \"reason\": \"LCP 超过 2.5 秒目标\"\n    }\n  ],\n  \"fallbackBranch\": \"finish\"\n}\n```\n\n外层 Decision 节点必须准确声明这里使用的 `optimize` 和 `finish` 分支 ID。\n\n## Host 选择器\n\n传入边界清晰的 `question`、结构化 `facts` 和可选 `guidance`。Runtime 会为当前对话创建 HostTask，并根据冻结 Decision 节点校验返回分支。它适合上下文判断，不负责修改代码、运行测试、部署或执行所选分支的业务动作。\n\n## 作者 API\n\n- `defineSelectorAtom`：使用自定义 ID 和 Signal 过期时间创建规则/用户选择器；\n- `defineHostSelectorAtom`：使用自定义 ID 和 HostTask 过期时间创建 Host 模型选择器。\n\n```bash\npnpm --filter @atom-workflow-agent/select-atom typecheck\npnpm --filter @atom-workflow-agent/select-atom test\n```\n\n参见 [Workflow 控制结构](../../docs/workflow-authoring.zh-CN.md#控制结构)。\n","readmeFilename":"README.zh-CN.md","_rev":"1-c2808072ea517d8696e7620c40a68936"}