Craft Agents craft-agent CLI 完整指南用终端管理标签、数据源、技能、自动化、权限与主题的六大配置域【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-osscraft-agent是 Craft Agents 项目中管理 workspace 配置域labels、sources、skills、automations 等的首选命令行接口。本文基于仓库内的官方指南 craft-cli.md 完整展开你将掌握全部六个实体的命令语法与示例、三种输入模式扁平 flag、--json、--stdin、统一的 JSON 输出契约与退出码约定并结合 cli-domains.ts 的源码实现理解 CLI 各域在 workspace 中的路径归属、只读动作白名单以及 Explore 模式下的 Bash 权限联动机制。一、CLI 总览与调用格式craft-agent的定位是 workspace 配置域的统一管理入口。官方指南 craft-cli.md 的开篇即给出调用范式craft-agent entity action [args] [--flags] [--json json] [--stdin]其中entity为六大配置域之一label/source/skill/automation/permission/themeaction为该域下的具体操作list、create、update 等。全局标志命令作用craft-agent --help打印帮助信息craft-agent --version查看版本craft-agent --discover发现能力discover三种输入模式扁平 flags适合简单值的快速操作例如--name Bug --color accent--json json传入结构化输入适合嵌套或批量更新例如--json {name:Bug Report,color:destructive}--stdin从管道读取 JSON 对象输入适合脚本组合场景。这种简单场景用 flag、复杂场景用 JSON的双轨设计贯穿全部六个域。值得注意的是指南中每个实体章节都被!-- cli:label:start --/!-- cli:label:end --之类的 HTML 注释标记包裹如 craft-cli.md 的 Label 章节从文档结构看这些段落是随 CLI 实现同步维护的参考区块保证命令参考与实现不漂移。二、Label 域workspace 标签管理标签存储于 workspace 的labels/目录。完整命令列表craft-agent label listcraft-agent label get idcraft-agent label create --name name [--color color] [--parent-id id|root] [--value-type string|number|date]craft-agent label update id [--name name] [--color color] [--value-type string|number|date|none] [--clear-value-type]craft-agent label delete idcraft-agent label move id --parent id|rootcraft-agent label reorder [--parent id|root] ordered-id-1 ordered-id-2 ...craft-agent label auto-rule-list idcraft-agent label auto-rule-add id --pattern regex [--flags gi] [--value-template $1] [--description ...]craft-agent label auto-rule-remove id --index ncraft-agent label auto-rule-clear idcraft-agent label auto-rule-validate id示例craft-agent label list craft-agent label get bug craft-agent label create --name Bug --color accent craft-agent label create --name Priority --value-type number craft-agent label update bug --json {name:Bug Report,color:destructive} craft-agent label update priority --value-type none craft-agent label move bug --parent root craft-agent label reorder --parent root development content bug craft-agent label auto-rule-add linear-issue --pattern \\b([A-Z]{2,5}-\\d)\\b --value-template $1 craft-agent label auto-rule-list linear-issue craft-agent label auto-rule-validate linear-issue要点Notes嵌套或批量更新使用--json/--stdinID 是创建时由 name 生成的稳定 slug用--value-type none或--clear-value-type移除标签值类型。自动规则auto-rule是标签的正则派生能力上面的示例中\b([A-Z]{2,5}-\d)\b匹配形如LINEAR-123的引用$1模板将捕获组写入标签值。auto-rule-validate用于校验规则本身的合法性。标签域更深入的背景可参考 labels.md。三、Source 域MCP / API / 本地数据源管理数据源存储于sources/{slug}/目录。命令列表craft-agent source list [--include-builtins true|false]craft-agent source get slugcraft-agent source createflag 见下表craft-agent source update slug --json {...}craft-agent source delete slugcraft-agent source validate slugcraft-agent source test slugcraft-agent source init-guide slug [--template generic|mcp|api|local]craft-agent source init-permissions slug [--mode read-only]craft-agent source auth-help slugsource create的完整 flag 表Flag说明--name name必填数据源显示名称--provider provider必填提供方标识如linear、github--type mcp\|api\|local必填数据源类型--enabled true\|false启用/禁用默认true--icon url-or-emoji图标 URL自动下载或 emojiMCP 专用--url urlMCP 服务器 URL--transport http\|stdioMCP 传输类型--auth-type oauth\|bearer\|noneMCP 认证类型API 专用--base-url urlapi 必填API base URL必须带末尾斜杠--auth-type bearer\|header\|query\|basic\|noneapi 必填API 认证类型Local 专用--path pathlocal 必填文件系统路径示例craft-agent source list craft-agent source get linear # MCP source with flat flags craft-agent source create --name Linear --provider linear --type mcp --url https://mcp.linear.app/sse --auth-type oauth # MCP source with --json for nested config craft-agent source create --name Linear --provider linear --type mcp --json {mcp:{transport:http,url:https://mcp.linear.app/sse,authType:oauth}} # API source craft-agent source create --name Exa --provider exa --type api --base-url https://api.exa.ai/ --auth-type header # Local source craft-agent source create --name Docs Folder --provider filesystem --type local --path ~/Documents craft-agent source update linear --json {enabled:false} craft-agent source validate linear craft-agent source test linear craft-agent source init-guide linear --template mcp craft-agent source init-permissions linear --mode read-only craft-agent source auth-help linear要点简单值用扁平 flag类型专属的嵌套配置字段mcp、api、local用--jsoninit-guide按数据源类型生成实用的guide.md脚手架init-permissions为 Explore 模式生成只读permissions.json模式auth-help返回会话内推荐的认证工具与模式test是轻量的 CLI 校验完整会话内认证/连接探测应使用source_testMCP 工具。四、Skill 域workspace 技能管理技能存储于skills/{slug}/SKILL.md。命令列表craft-agent skill list [--workspace-only] [--project-root path]craft-agent skill get slug [--project-root path]craft-agent skill where slug [--project-root path]craft-agent skill createflag 见下表craft-agent skill update slug --json {...} [--project-root path]craft-agent skill delete slugcraft-agent skill validate slug [--source workspace|project|global] [--project-root path]skill create的 flag 表Flag说明--name name必填技能显示名称--description desc必填简短描述1-2 句--slug slug自定义 slug省略时从 name 自动生成--body ...技能内容/指令markdown 正文--icon url图标 URL自动下载为icon.*--globs *.ts,*.tsx逗号分隔的 glob 模式用于自动建议--always-allow Bash,Write逗号分隔的始终允许工具名--required-sources linear,github逗号分隔的需自动启用的 source slug示例craft-agent skill list craft-agent skill list --workspace-only craft-agent skill where commit-helper craft-agent skill create --name Commit Helper --description Generate conventional commits --slug commit-helper craft-agent skill create --name Code Review --description Review PRs --globs *.ts,*.tsx --always-allow Bash --required-sources github craft-agent skill update commit-helper --json {requiredSources:[github],body:Use concise, imperative commit messages.} craft-agent skill validate commit-helper craft-agent skill validate commit-helper --source global craft-agent skill delete commit-helper要点create/update会写入SKILL.md的 frontmatter 与正文内容where用于检查 project / workspace / global 三级解析优先级--project-root将解析范围限定到某个项目目录默认 cwd。五、Automation 域事件驱动的自动化管理自动化存储于automations.json。命令列表craft-agent automation listcraft-agent automation get idcraft-agent automation createflag 见下表craft-agent automation update id与 create 相同 flag全部可选craft-agent automation delete idcraft-agent automation enable idcraft-agent automation disable idcraft-agent automation duplicate idcraft-agent automation history [id] [--limit n]craft-agent automation last-executed idcraft-agent automation test id [--match ...]craft-agent automation lintcraft-agent automation validateautomation create/update的 flag 表Flag说明--event EventNamecreate 必填事件触发器如UserPromptSubmit、SchedulerTick、LabelAdd--name name自动化显示名称--matcher regex事件匹配的正则模式--cron expressionCron 表达式用于SchedulerTick事件--timezone tzIANA 时区如Europe/Budapest--permission-mode safe\|ask\|allow-all所创建会话的权限级别--enabled true\|false启用/禁用该自动化--labels label1,label2逗号分隔的所创建会话标签--prompt ...提示词文本自动创建一个 prompt action--llm-connection slug所创建会话的 LLM 连接 slug--model model-id所创建会话的模型 ID示例craft-agent automation list craft-agent automation validate # Simple prompt automation with flat flags craft-agent automation create --event UserPromptSubmit --prompt Summarize this prompt # Scheduled automation with flat flags craft-agent automation create --event SchedulerTick --cron 0 9 * * 1-5 --timezone Europe/Budapest --prompt Give me a morning briefing --labels Scheduled --permission-mode safe # Complex automation with --json craft-agent automation create --event SchedulerTick --json {cron:0 9 * * 1-5,actions:[{type:prompt,prompt:Daily summary}]} craft-agent automation update abc123 --name Morning Report --prompt Updated prompt craft-agent automation update abc123 --enabled false craft-agent automation enable abc123 craft-agent automation duplicate abc123 craft-agent automation history abc123 --limit 10 craft-agent automation last-executed abc123 craft-agent automation test abc123 --match UserPromptSubmit craft-agent automation lint craft-agent automation delete abc123要点简单自动化用扁平 flag带复杂 matcher 与多个actions的自动化用--json--prompt是快捷方式自动将文本包装为 prompt action多 action 自动化须用--json的actions字段lint提供快速的 matcher/action 卫生检查正则合法性、缺失 action、超大的 prompt mention 集合history与last-executed在存在时读取automations-history.jsonlvalidate执行完整的 schema 与语义检查。自动化机制本身事件总线、调度、重试可进一步参考 automations.md。六、Permission 域Explore 模式权限管理Explore 模式权限存储于permissions.jsonworkspace 级与每个 source 级。命令列表craft-agent permission listcraft-agent permission get [--source slug]craft-agent permission set [--source slug] --json {...}craft-agent permission add-mcp-pattern pattern [--comment ...] [--source slug]craft-agent permission add-api-endpoint --method GET|POST|... --path regex [--comment ...] [--source slug]craft-agent permission add-bash-pattern pattern [--comment ...] [--source slug]craft-agent permission add-write-path glob [--source slug]craft-agent permission remove index --type mcp|api|bash|write-path|blocked [--source slug]craft-agent permission validate [--source slug]craft-agent permission reset [--source slug]作用域Scope不带--source操作 workspace 级permissions.json全局规则带--source slug操作该 source 自己的permissions.json自动作用域化。示例# List all permissions files (workspace sources) craft-agent permission list # Get workspace permissions craft-agent permission get # Get source-specific permissions craft-agent permission get --source linear # Add read-only MCP patterns for a source craft-agent permission add-mcp-pattern list --comment List operations --source linear craft-agent permission add-mcp-pattern get --comment Get operations --source linear craft-agent permission add-mcp-pattern search --comment Search operations --source linear # Add API endpoint rules craft-agent permission add-api-endpoint --method GET --path .* --comment All GET requests --source stripe # Add bash patterns craft-agent permission add-bash-pattern ^ls\\s --comment Allow ls # Add write path globs craft-agent permission add-write-path /tmp/** # Remove a rule by index and type craft-agent permission remove 1 --type mcp --source linear # Replace entire config craft-agent permission set --source github --json {allowedMcpPatterns:[{pattern:list,comment:List ops}]} # Validate all permissions craft-agent permission validate # Validate source-specific craft-agent permission validate --source linear # Delete permissions file (revert to defaults) craft-agent permission reset --source linear要点source 级 MCP 模式在运行时自动作用域化如list会变成mcp__slug__.*listremove使用指定规则类型数组内的 0 起始索引可先用get查看索引validate执行 schema 正则校验不带--source时校验 workspace 与全部 sourcereset删除权限文件回退到默认值。七、Theme 域应用级与 workspace 级主题管理命令列表craft-agent theme getcraft-agent theme validate [--preset id]craft-agent theme list-presetscraft-agent theme get-preset idcraft-agent theme set-color-theme idcraft-agent theme set-workspace-color-theme id|defaultcraft-agent theme set-override --json {...}craft-agent theme reset-override示例# Inspect current theme state craft-agent theme get # Validate app override file craft-agent theme validate # Validate one preset file craft-agent theme validate --preset nord # List available presets craft-agent theme list-presets # Inspect a specific preset craft-agent theme get-preset dracula # Set app default preset craft-agent theme set-color-theme nord # Set workspace override craft-agent theme set-workspace-color-theme dracula # Clear workspace override (inherit app default) craft-agent theme set-workspace-color-theme default # Replace app-level theme.json override craft-agent theme set-override --json {accent:oklch(0.62 0.21 293),dark:{accent:oklch(0.68 0.21 293)}} # Remove app-level override file craft-agent theme reset-override要点set-color-theme与set-workspace-color-theme需要一个已存在的 preset IDdefault始终有效set-override在写入前校验theme.json的形状workspace 级覆盖保存在workspace/config.json的defaults.colorTheme下应用级覆盖保存在~/.craft-agent/theme.json。主题实现细节可参考 themes.md 与 permissions.md、sources.md、skills.md。八、输出契约Output Contract所有命令在 stdout 上返回单一 JSON 信封envelope。成功{ ok: true, data: {}, warnings: [] }错误{ ok: false, error: { code: USAGE_ERROR, message: ..., suggestion: ... }, warnings: [] }退出码Exit codes退出码含义0成功1执行/内部失败2用法/校验/输入失败这个契约对脚本集成非常友好判断ok字段与退出码即可区分业务失败与参数写错且错误对象自带suggestion修复建议便于 CI 与 Agent 消费输出。九、源码纵深CLI 域策略与 Explore 模式权限联动仓库中 cli-domains.ts 是理解craft-agentCLI 与宿主系统集成关系的关键文件。它定义了六个命名空间label | source | skill | automation | permission | theme见 CliDomainNamespace 类型定义并为每个域声明一个CliDomainPolicy策略POLICIES 记录包含四个维度workspacePathScopes该域在 workspace 中拥有的路径作用域与文档各章节的存储位置描述一一对应——label→labels/**source→sources/**skill→skills/**automation→automations.json、automations-history.jsonlpermission→permissions.json、sources/*/permissions.jsontheme→config.json、theme.json、themes/*.jsonreadActions该域的只读动作白名单。例如label的只读动作为list、get、auto-rule-list、auto-rule-validatesource为list、get、validate、test、auth-help。这与指南中各域命令列表严格对应说明文档中的只读命令不是随意的而是由策略表驱动的。bashGuardPaths对直接 Bash 操作加守卫的 workspace 相对路径防止 Agent 绕过 CLI 直接改写配置文件如labels/**、automations.json。quickExamples每个域的速查示例供帮助输出或 Agent 提示词引用。更值得关注的是 getCraftAgentReadOnlyBashPatterns()它从上述策略程序化派生Explore 模式的只读craft-agentBash 权限模式例如针对每个命名空间生成形如^craft-agent\slabel\s(list|get|auto-rule-list|auto-rule-validate)\b的正则并额外放行裸调用打印帮助、实体 help 与全局标志--help/--version/--discover。这意味着Explore 模式下 Agent 可以安全执行只读的craft-agent命令list/get/validate 等而写操作默认被权限层拦截权限正则与命令元数据来自同一张策略表二者天然对齐避免了文档说允许、权限表却拦截的漂移仓库随附的默认权限文件 default.json 中同样包含craft-agent相关规则与策略表中的读动作模式相互印证。此外source init-permissions slug --mode read-only生成的正是这类只读 MCP 模式规则的脚手架如指南示例中对linear依次添加list/get/search模式与上述权限机制形成闭环CLI 既管理被保护的配置域本身也生成保护这些域运行时访问的权限规则。十、实践建议小结先读后写任何改动前先list/getvalidate放在create/update之后作为收尾动作flag 与--json的分工单值字段走扁平 flag嵌套配置mcp/api/local子对象、多actions走--json管道场景走--stdinExplore 模式集成只读命令集合由 cli-domains.ts 的readActions决定为 Agent 配置权限时以此为权威来源退出码驱动脚本在 CI/脚本中优先检查退出码0/1/2与 JSON 信封中的ok、error.code字段而不是解析人类可读文本与 MCP 工具互补source test只是轻量 CLI 校验会话内的完整连接探测仍应使用source_testMCP 工具。参考文档craft-cli.md、cli-domains.ts、default.json。【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考