noodle

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Noodle

Skills that run themselves. Write skills with a

schedule:

field describing when they should run. Noodle's scheduler agent reads those descriptions, writes orders, and the loop spawns agents in isolated worktrees to do the work.

可自主运行的Skill。你可以为Skill编写

schedule:

字段来描述其运行条件。Noodle的调度Agent会读取这些描述，生成orders，并在循环中于隔离的worktree内启动Agent执行任务。

How the Loop Works

循环工作原理

Brief — Noodle gathers project state into
```
.noodle/mise.json
```
(backlog, active agents, history, capacity, registered skills)
Schedule — the scheduler agent reads mise, writes
```
.noodle/orders-next.json
```
Dispatch — Noodle promotes orders and spawns agent sessions
Execute — each agent runs in its own worktree with the assigned skill
Merge — completed work merges back to main

概要（Brief） — Noodle将项目状态汇总到
```
.noodle/mise.json
```
中（包含待办队列、活跃Agent、历史记录、容量、已注册Skill）
调度（Schedule） — 调度Agent读取mise信息，生成
```
.noodle/orders-next.json
```
分发（Dispatch） — Noodle提升orders优先级并启动Agent会话
执行（Execute） — 每个Agent在分配给它的worktree中运行对应的Skill
合并（Merge） — 完成的工作会合并回主分支

Skills

Skill

A skill is a directory with a

SKILL.md

. The body is the agent's instructions. The frontmatter is metadata.

General skills (no

schedule:

) are invoked directly by agents. Examples:

commit

debugging

Scheduled skills (with

schedule:

) run autonomously. The scheduler reads the

schedule:

value as prose and uses judgment to decide when conditions are met.

yaml

---
name: quality
description: Post-cook quality gate.
schedule: "Follow-up stage after execute. Cross-provider review preferred."
---

Skills live in

.agents/skills/

by default. Paths in

skills.paths

are searched in order; first match wins.

For the full guide on writing skills, orders, and schedule fields, see references/skill-authoring.md.

一个Skill就是包含

SKILL.md

文件的目录。文件正文是Agent的执行指令，frontmatter是元数据。

通用Skill（无

schedule:

字段）由Agent直接调用。例如：

commit

、

debugging

。

定时Skill（带有

schedule:

字段）可自主运行。调度器会将

schedule:

的值作为自然语言描述读取，并通过判断决定何时满足运行条件。

yaml

---
name: quality
description: Post-cook quality gate.
schedule: "Follow-up stage after execute. Cross-provider review preferred."
---

Skill默认存放在

.agents/skills/

目录下。系统会按顺序搜索

skills.paths

中配置的路径，以第一个匹配结果为准。

关于编写Skill、orders和schedule字段的完整指南，请参阅references/skill-authoring.md。

Configuration

配置

Noodle reads

.noodle.toml

at project root. Scaffolded on first

noodle start

. Most projects only need:

toml

mode = "supervised"  # auto | supervised | manual

[routing.defaults]
provider = "claude"
model = "claude-opus-4-6"

[skills]
paths = [".agents/skills"]

Full config reference: references/configuration.md

Noodle会读取项目根目录下的

.noodle.toml

文件，该文件会在首次执行

noodle start

时自动生成。大多数项目只需要以下配置：

toml

mode = "supervised"  # auto | supervised | manual

[routing.defaults]
provider = "claude"
model = "claude-opus-4-6"

[skills]
paths = [".agents/skills"]

完整配置参考：references/configuration.md

CLI

All commands accept

--project-dir

(default: current directory, env:

NOODLE_PROJECT_DIR

所有命令都支持

--project-dir

参数（默认值：当前目录，环境变量：

NOODLE_PROJECT_DIR

）。

Core

核心命令

Command	Description
`noodle start`	Start the noodle loop
`noodle start --once`	Run one scheduling cycle and exit
`noodle status`	Show runtime status (active agents, queue depth, loop state)
`noodle reset`	Clear all runtime state (refuses if loop is running)

Command	Description
`noodle start`	启动noodle循环
`noodle start --once`	运行一次调度周期后退出
`noodle status`	显示运行时状态（活跃Agent、队列深度、循环状态）
`noodle reset`	清除所有运行时状态（循环运行时会拒绝执行）

Skills & Schemas

Skill与Schema

Command	Description
`noodle skills`	List resolved skills
`noodle skills list`	List all resolved skills
`noodle schema <target>`	Print schema docs for a target
`noodle schema list`	List available schema targets ( `mise` , `orders` , `status` )

Command	Description
`noodle skills`	列出已解析的Skill
`noodle skills list`	列出所有已解析的Skill
`noodle schema <target>`	打印指定目标的schema文档
`noodle schema list`	列出可用的schema目标（ `mise` 、 `orders` 、 `status` ）

Worktrees

Worktree

Command	Description
`noodle worktree create <name>`	Create a new linked worktree
`noodle worktree create <name> --from <ref>`	Create from a specific branch or commit
`noodle worktree exec <name> <command...>`	Run a command inside a worktree (CWD-safe)
`noodle worktree merge <name>`	Merge a worktree branch into integration branch
`noodle worktree merge <name> --into <branch>`	Merge into a specific target branch
`noodle worktree list`	List all worktrees with merge status
`noodle worktree prune`	Remove merged and patch-equivalent worktrees
`noodle worktree cleanup <name>`	Remove a worktree without merging
`noodle worktree cleanup <name> --force`	Remove even with unmerged commits
`noodle worktree hook`	Run worktree session hook (used internally)

Command	Description
`noodle worktree create <name>`	创建一个新的关联worktree
`noodle worktree create <name> --from <ref>`	从指定分支或提交创建worktree
`noodle worktree exec <name> <command...>`	在worktree内运行命令（CWD安全）
`noodle worktree merge <name>`	将worktree分支合并到集成分支
`noodle worktree merge <name> --into <branch>`	合并到指定的目标分支
`noodle worktree list`	列出所有worktree及其合并状态
`noodle worktree prune`	移除已合并和补丁等效的worktree
`noodle worktree cleanup <name>`	移除worktree但不合并
`noodle worktree cleanup <name> --force`	强制移除，即使存在未合并的提交
`noodle worktree hook`	运行worktree会话钩子（内部使用）

Events

事件

Command	Description
`noodle event emit <type>`	Emit an external event into the loop
`noodle event emit <type> --payload <json>`	Emit with a JSON payload
`noodle event emit <type> --session <id>`	Emit to a specific session's event log

Full CLI reference: https://poteto.github.io/noodle/reference/cli

Command	Description
`noodle event emit <type>`	向循环中发送外部事件
`noodle event emit <type> --payload <json>`	发送携带JSON payload的事件
`noodle event emit <type> --session <id>`	发送到指定会话的事件日志中

完整CLI参考文档：https://poteto.github.io/noodle/reference/cli

Troubleshooting

故障排除

"fatal config diagnostics prevent start" — Check
```
.noodle.toml
```
against
```
noodle schema
```
.
Missing adapter scripts — Create scripts or update paths in config.

Stale worktrees —

noodle worktree list

, then

noodle worktree prune

“fatal config diagnostics prevent start”（致命配置诊断错误导致无法启动） — 对照
```
noodle schema
```
检查
```
.noodle.toml
```
文件。
缺少adapter脚本 — 创建脚本或更新配置中的路径。
Worktree过期 — 先运行
```
noodle worktree list
```
，再执行
```
noodle worktree prune
```
。

References

参考资料

references/skill-authoring.md — writing skills: pipeline, orders schema, schedule fields, stage composition, full examples
references/configuration.md — full .noodle.toml config reference
https://poteto.github.io/noodle/concepts/adapters — adapter setup, script contracts, provider examples
https://poteto.github.io/noodle/concepts/scheduling — how the loop schedules and dispatches work
https://poteto.github.io/noodle/concepts/skills — skill discovery, composition, scheduled vs general
https://poteto.github.io/noodle/concepts/runtimes — process, sprites, and runtime routing

references/skill-authoring.md — Skill编写：流水线、orders schema、schedule字段、阶段组合、完整示例
references/configuration.md — 完整的.noodle.toml配置参考
https://poteto.github.io/noodle/concepts/adapters — adapter配置、脚本约定、provider示例
https://poteto.github.io/noodle/concepts/scheduling — 循环如何调度和分发任务
https://poteto.github.io/noodle/concepts/skills — Skill发现、组合、定时Skill与通用Skill的区别
https://poteto.github.io/noodle/concepts/runtimes — 进程、sprite与运行时路由