Cline 定时自动化实战dependency-check 依赖健康巡检 Cron Spec 全解析【免费下载链接】clineAutonomous coding agent as an SDK, IDE extension, or CLI assistant.项目地址: https://gitcode.com/GitHub_Trending/cl/cline本文以 Cline SDK 官方示例dependency-check.cron.md每周依赖健康巡检为主体完整拆解这份 Markdown 自动化规范的每个 frontmatter 字段与提示词正文并结合cline/core中 cron 子系统解析器、调度器、运行器、报告写入器的真实源码说明一个.cron.md文件从落盘到被解析、校验、入队、执行、产出报告的完整链路。读完本文你可以直接复制该模板为自己的项目配置定时依赖巡检并理解每个配置项在底层是如何生效的。一、示例规范全文一份生产可用的依赖巡检 Specsdk/examples/cron/dependency-check.cron.md 是 Cline Automation Examples 目录下每周安全巡检场景的官方模板。其完整内容如下可直接复制--- id: dependency-check title: Weekly Dependency Health Check workspaceRoot: /absolute/path/to/repo schedule: 0 10 * * MON tools: run_commands,read_files mode: act enabled: false modelSelection: providerId: cline modelId: anthropic/claude-opus-4.7 timeoutSeconds: 1800 maxIterations: 15 tags: - automation - security - dependencies metadata: owner: platform --- Run a comprehensive dependency health check: 1. Check for outdated packages: npm outdated (or yarn/pnpm equivalent) 2. Check for security vulnerabilities: npm audit 3. List packages with available major version upgrades 4. Identify unused dependencies (if possible) 5. Check for dependency conflicts or duplicate packages Provide a summary report covering: - Critical security vulnerabilities (if any) - Count of outdated packages by severity (minor, patch, major) - Recommended immediate actions - Packages safe to update to latest versions Focus on actionable insights. Ignore known false positives and dev-only dependencies.这份规范分为两部分YAML frontmatter 声明何时、如何、用哪个模型执行Markdown 正文则是发给 Agent 的任务提示词prompt。下面逐字段拆解并对照源码说明每个字段被谁消费、如何校验。1. 调度相关字段字段示例值说明iddependency-check规范唯一标识字母数字与连字符在 解析器 中若省略则回退为文件相对路径见cron-spec-parser.ts#L294-L295titleWeekly Dependency Health Check人类可读标题省略时回退为id或文件名主干cron-spec-parser.ts#L395-L398并会出现在每次运行报告的标题中workspaceRoot/absolute/path/to/repo必填目标项目绝对路径运行时作为工作目录cwd。解析器中缺失会直接判定为invalidcron-spec-parser.ts#L353-L363错误信息为workspaceRoot is requiredschedule0 10 * * MON.cron.md规范必填5 段 cron 表达式分、时、日、月、周即每周一上午 10:00。缺失时报错schedule is required for *.cron.md specscron-spec-parser.ts#L421-L430timezone本例省略可选 IANA 时区如America/New_York缺省使用系统时区。表达式与时区在解析阶段即被校验见下文调度器小节一个容易忽略的细节文件名后缀决定触发类型。cron-spec-parser.ts 中的inferTriggerKindFromPathL28-L39按路径推断位于events/且以.event.md结尾的是事件驱动规范以.cron.md结尾的是周期调度规范普通.md则是一次性one-off规范。而且schedule、timezone是仅.cron.md允许的字段L297-L310写在事件规范里会解析失败——这从源码层面保证了三类规范.cron.md/.event.md/ 一次性字段的互斥边界。2. 执行约束字段字段示例值底层行为toolsrun_commands,read_files工具白名单。支持逗号分隔字符串或 YAML 数组normalizeStringListcron-spec-parser.ts#L99-L120每个名称必须属于合法工具集合否则整体报错unknown tool(s): ...L124-L132。运行期转换为工具策略白名单外的所有工具被禁用ask_question因无人值守被强制禁用详见运行器小节modeact仅允许act/plan/yolonormalizeModeL92-L97非法值报mode must be one of: act, plan, yolo。省略时默认yoloL401。act表示允许执行命令依赖巡检需要跑npm outdated/npm audit所以这里用act而非只读的planenabledfalse布尔值缺省为trueL411-L414。示例自带false意味着复制模板后若忘记开启规范永远不会被入队——materializer 只处理enabled: true的规范见下文modelSelection{ providerId: cline, modelId: anthropic/claude-opus-4.7 }覆盖本次运行的模型/供应商。解析器只接受providerId、modelId两个字符串键normalizeModelSelectionL81-L90timeoutSeconds1800单次运行超时30 分钟必须是正数asPositiveIntL155-L160。运行器用withTimeout竞速包装整个会话轮次超时抛cron run timed outcron-runner.tsmaxIterations15Agent 最大迭代轮数上限同样是正整数L404systemPrompt本例省略可选自定义系统提示词字符串空白会被忽略L402tagsautomation, security, dependencies任意分组标签解析为字符串数组normalizeTagsL66-L72metadata{ owner: platform }自由元数据对象仅接受非数组对象normalizeRecordL74-L79本例用于标记归属团队frontmatter 之外还有一个隐式约定正文即 prompt。解析器规定 prompt 必须来自 frontmatter 的prompt字段或Markdown 正文二者皆空则解析失败cron-spec-parser.ts#L338-L351。本示例选择正文承载提示词这也是 自动化示例 README 推荐的方式——提示词用自然语言写可读性最好。3. 提示词正文五步检查 结构化报告正文部分是这份示例真正的业务逻辑值得逐条对照理解检查步骤交给 Agent 的五项任务检查过期包npm outdated或 yarn/pnpm 等价命令检查安全漏洞npm audit列出有可用大版本major升级的包尽可能识别未使用的依赖检查依赖冲突或重复包。报告要求Agent 产出物严重安全漏洞若有按严重级别minor / patch / major统计的过期包数量建议的立即处理动作可安全升级到最新版本的包清单。最后一句约束值得借鉴Focus on actionable insights. Ignore known false positives and dev-only dependencies.聚焦可执行的洞察忽略已知误报与纯开发依赖。这是对 LLM 输出的降噪指令避免周报式的噪音报告。配合tools: run_commands,read_files的白名单Agent 被限定只能执行命令和读文件——它能跑npm outdated/npm audit、读package.json做未使用依赖分析但不能改文件、不能打补丁巡检天然是只读安全的。二、调度器如何理解0 10 * * MONschedule字段在解析阶段就会通过 scheduler.ts 中的validateCronSchedule严格校验cron-spec-parser.ts#L431-L443。从源码结构看Cline 没有引入第三方 cron 库而是自实现了一个纯函数解析器parseCronFieldscheduler.ts#L1-L76逐字段展开支持*全量展开、a-b区间、a/step步进、a,b,c列表四种语法的组合月份和星期支持英文缩写MONTH_NAMES/DOW_NAMESL78-L93所以0 10 * * MON中的MON会被解析为星期值 1数值越界、倒序区间、非法步进都会抛出带上下文的错误如Invalid cron value X for range [min-max]L18-L205 个字段全部必填缺字段时报missing field NL111-L120。校验失败的规范不会让 hub 崩溃——解析器从不抛异常而是返回带error的CronSpecParseResult由对账器reconciler把该文件持久化记录为parse_statusinvalid见 cron-spec-parser.ts 顶部注释 L16-L26。也就是说改坏了schedule表达式只会让这一份规范失效并留痕不影响其他规范。timezone字段允许用 IANA 时区名固定巡检时刻对跨时区团队尤其有用不设时区时按宿主系统时区的周一 10:00 触发。三、从落盘到执行这份 Spec 的完整运行链路理解执行链路才能解释为什么示例默认enabled: false以及运行结果去哪儿看。以下全部来自cline/core的 cron 子系统源码1. 发现与解析hub/SDK 启用自动化后会扫描 cron 规范目录默认为全局~/.cline/cron/见 cron-report-writer.ts 注释 L14-L19 与 shared storage 的resolveCronSpecsDir。每个文件经过parseCronSpecFile解析并计算 frontmatter 与正文的 SHA-256 内容哈希computeContentHashcron-spec-parser.ts#L185-L194用于检测文件变更并驱动重新对账。2. 物化入队cron-materializer.ts 是何时创建运行记录的唯一决策点。materializeAll()L35 起只挑选triggerKind: schedule、enabled: true、parseStatus: valid三类条件同时满足的规范来计算下次运行时间并入队——这就是模板里enabled: false的完整语义文件已就位、已解析但不会占用任何执行资源。把示例中该行改为true或直接删除因缺省即为true即可激活。3. 轮询与认领cron-runner.ts 是一个触发源无关的执行器每 N 秒轮询 cron.db原子认领队列中的运行执行后事务性持久化状态文件头部注释 L25-L32。默认轮询间隔 15 秒、认领租约 90 秒L34-L35多个运行器实例可安全共存。4. 工具策略的落实buildToolPoliciescron-runner.ts#L61-L85精确实现了tools白名单语义——若指定了tools先以*: { enabled: false, autoApprove: true }全量禁用再逐个开启白名单内工具ask_question被强制禁用注释写明定时运行是无人值守的不能等待人工响应L72-L77mode: yolo时额外放开submit_and_exit。因此dependency-check运行时Agent 唯一可用的工作工具就是run_commands和read_files且所有调用自动批准、无需交互。5. 超时与迭代上限整个会话轮次被withTimeoutL106-L122包装timeoutSeconds: 1800到期即拒绝并标记失败maxIterations: 15约束 Agent 的工具调用轮数两者共同兜底依赖检查跑飞的场景。6. 报告落盘每次完成或失败cron-report-writer.ts 会在cron-specs-dir/reports/run-id.md默认~/.cline/cron/reports/写入 Markdown 报告含 YAML frontmatter运行 ID、状态、耗时、token 用量、执行摘要、工具调用与结果写入前对用户可控文本做转义escapeMarkdownInlineL79-L83防止规范标题里的特殊字符破坏报告结构。数据库仍是操作事实源报告是可再生的派生产物注释 L16-L19。四、部署步骤与启用自动化结合 sdk/examples/cron/README.md 的官方指引在自有项目中启用这份依赖巡检模板# 1. 创建规范目录全局 mkdir -p ~/.cline/cron # 2. 复制模板路径以仓库 sdk/examples/cron/ 为源 cp sdk/examples/cron/dependency-check.cron.md ~/.cline/cron/# 3. 编辑规范必须改 # - workspaceRoot → 你的项目绝对路径 # - enabled → true或直接删除该行缺省即启用 # - modelSelection → 你可用的 providerId/modelId # - schedule/timezone → 按需调整然后按集成方式之一开启自动化Hub 中new HubWebSocketServer({ cronOptions: { workspaceRoot: /absolute/workspace } });SDK 中const cline await ClineCore.create({ automation: true, // Enable automation // ... other options });规范在启动时对账reconcile并自动入队下一次运行无需手动触发。运行结束后到~/.cline/cron/reports/查看dependency-check的巡检报告严重漏洞、分级过期统计、建议动作一目了然。更多上下文可参考 sdk/ARCHITECTURE.md 中 automation 一节的运行时架构说明以及同目录下的事件驱动示例 plugins/automation-events.ts——若希望把发现严重漏洞进一步升级为即时事件响应可以在巡检报告基础上接入事件规范。五、实践要点小结模板默认禁用是刻意设计enabled: false让示例可以安全地随仓库分发而不产生运行复制后第一件事就是将其改为true。workspaceRoot是硬性必填它既是解析校验项也是运行时的工作目录cwd旧字段cwd已被移除使用会直接导致解析失败cron-spec-parser.ts#L211-L222。act 只读工具白名单是安全巡检的正确组合允许执行npm命令同时通过工具策略杜绝写操作。timeoutSeconds: 1800与maxIterations: 15要按项目规模调整大型 monorepo 的npm audit可能超过 30 分钟此时应调大超时或改用pnpm系工具。改坏了规范不会拖垮其他规范解析失败只把单个文件标记为invalid并留痕其余规范照常调度——这是永不抛异常解析器设计带来的运维友好性。提示词正文决定报告质量示例中按 severity 分级统计 只报可执行建议 忽略 dev-only 依赖的写法是定制其他巡检类规范如许可证检查、lockfile 漂移时值得直接套用的模板。【免费下载链接】clineAutonomous coding agent as an SDK, IDE extension, or CLI assistant.项目地址: https://gitcode.com/GitHub_Trending/cl/cline创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考