Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ A workflow of about 25 nodes takes around 10 minutes. A large workflow can take

## What you get

<!-- before / after image goes here -->
<img width="1920" height="1080" alt="ba_04_allinone_dark" src="https://github.com/user-attachments/assets/b2218290-7b18-4810-bb62-7a27d1dfe332" />

- **The rebuilt workflow**: a `.json` file with `_readable` appended to the original name. The original file is not overwritten.
- **report.html**: open it in a browser to watch the AI rebuild the workflow and read an explanation of the result.
Expand Down
24 changes: 18 additions & 6 deletions skills/comfyui-readable-node/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,12 +60,23 @@ The rules in the references serve these principles and goals; how to read a rule

## Steps

`S` is the path of scripts/. Choose one working folder `W` inside the folder where the results go (the one the user named; otherwise next to the original), and type every canvas move as `python3 $S/canvas.py --dir $W <move>`. Below, this is written `canvas`. The list of moves, their syntax and the detailed behavior (undo, placements calculated only once, block, and so on) are at the top of canvas.py (`python3 $S/canvas.py` prints them): read it once before step 4.
`S` is the path of scripts/. The results go in the folder the user named; otherwise next to the original, or the current folder when there is no original. Make one working folder `W` there for this job, named after the workflow it builds with `_work` after it (`image_flux2_klein_text_to_image_work`, `flux_text_to_image_work`), and type every canvas move as `python3 $S/canvas.py --dir $W <move>`. Below, this is written `canvas`. The list of moves, their syntax and the detailed behavior (undo, placements calculated only once, block, and so on) are at the top of canvas.py (`python3 $S/canvas.py` prints them): read it once before step 4.
- Put every file you make while working inside `W`: plan files (build.txt for building, layout.txt for arranging: "the plan" is layout.txt), Note files, workflows or object_info you fetch to read, notes. Only the exported workflows and the report page go outside `W`. `canvas finish` deletes the files of `W` it knows (what it wrote, the plan and Note files, understanding.md) and names the others it left: delete only those, one by one. Do not delete `W` with a recursive delete.

Moves marked "(when there is an original)" are only for rebuilding a given workflow. When building a new one, skip them.

When the user asks for it fast, skip steps 9 and 10 (the review and the report page), finish with `canvas finish fast`.
Which steps apply. Moves marked "(when there is an original)" in the steps are only for rebuilding a given workflow. "Fast" is when the user asks for it fast; it applies to both.

| Step | Rebuilding a given workflow | Building a new one | Fast | Done before the next step |
|---|---|---|---|---|
| 1 Read | `open <workflow.json> <object_info>`, `src all` | `open new <object_info>` (only the node definitions) | same | the working folder is open |
| 2 Understanding | A to E of references/understanding.md | what was asked: what it makes, what the user puts in and gets out | same | understanding.md |
| 3 Split | yes | yes | same | the canvases |
| 4 Build | `copy` and `add`, then `diff` | `add` only | same | the wires are connected |
| 5–6 Arrange, look and fix | yes | yes | same | what the check names is fixed |
| 7 Notes | yes | yes | same | the Notes |
| 8 Export | the original's name with `_readable`, `diff` | a few English words for what it does | same | the exported workflows |
| 9 Review | yes | yes | skipped | the review registered |
| 10 Report page | with Original | without Original | skipped | report.html |
| 11 Report and finish | `finish` | `finish` | `finish fast` | the working folder is gone |

1. **Read the original (when there is an original)**
`canvas open <workflow.json> <object_info URL or saved object_info JSON>`
Expand All @@ -77,6 +88,7 @@ When the user asks for it fast, skip steps 9 and 10 (the review and the report p
The understanding of the workflow, written before building. Write the first version after reading, and revise it while building. Keep what you revised as well.
- Read references/content.md, references/techniques.md, and the "Content" and "Notes" parts of references/examples.md before writing (its "Layout" part comes in step 5). readable-form.md, notes.md and review.md are read in steps 5, 7 and 9, not now.
- What to write is in references/understanding.md. For every node, write what it does with its values here.
- When building a new one, write only what was asked: what the workflow makes, what the user puts in and gets out.

3. **Split**
Following the split in the understanding document, make one canvas per workflow (`canvas new <name>`, `canvas use <name>`). How they are named is in step 8. One canvas becomes one workflow JSON.
Expand Down Expand Up @@ -123,13 +135,13 @@ When the user asks for it fast, skip steps 9 and 10 (the review and the report p
- One Note at a time, check that the node on the 🔗 line and the topics are about the same node; a topic about another node moves to that node's Note.

8. **Export and compare**
For each canvas, `canvas export <name>.json`. The name is the original's file name with `_readable` after it (`image_flux2_klein_text_to_image_readable.json`), so it stands beside the original without overwriting it; when the workflow was split, a few English words after that say what each one does (`…_readable_upscale.json`). (When there is an original) run `canvas diff` again on every canvas, take the differences one by one against the four items of step 4 and content.md, "What becomes of each part", fix what they say, and export again.
For each canvas, `canvas export <name>.json`. The name is the original's file name with `_readable` after it (`image_flux2_klein_text_to_image_readable.json`), so it stands beside the original without overwriting it; when the workflow was split, a few English words after that say what each one does (`…_readable_upscale.json`). When there is no original, the name is a few English words for what it does (`flux_text_to_image.json`). (When there is an original) run `canvas diff` again on every canvas, take the differences one by one against the four items of step 4 and content.md, "What becomes of each part", fix what they say, and export again.

9. **Review (another agent)**
Read references/review.md and follow it: draw the picture for each canvas (not for one that differs from another only in values), give the brief to a new agent, fix the rows one at a time, answer every row, export again and register the review with `canvas review`.

10. **Write the report page (`report.html`)**
Write the page where the user checks the result, as one HTML file. The page has three views. The canvas makes Original (the original workflow) and Rebuilt (what was done on the canvases, one move at a time). You write only the Walkthrough.
Write the page where the user checks the result, as one HTML file. The page has three views. The canvas makes Original (the original workflow; only when there is an original) and Rebuilt (what was done on the canvases, one move at a time). You write only the Walkthrough.
- For each canvas, write `$W/walk_<canvas>.md`, select the canvas with `canvas use <canvas>`, and register it with `canvas walk $W/walk_<canvas>.md` (the file's form is at the top of canvas.py). How to write it is in references/notes.md, "Walkthrough".
- Set the order of the canvases on the page with `canvas order <canvas> …`: the basic workflow on the left, then those that add to it (t2i before i2i and edit, the normal version before its fast version), parts last. Workflows of the same form that differ only in values (one per model) share one tab: write them next to each other as `<tab>/<canvas>`.
- Finally, write the page with `canvas report report.html <the user's language code>` (`ja`, `en`, `zh` and so on).
Expand Down
4 changes: 2 additions & 2 deletions skills/comfyui-readable-node/references/report.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@
2. The folder of the files, once. Under it, each file name as a bullet, with nested lines:
- What the workflow makes, from what. From the second workflow on, with how it differs ("The same video, with Turbo LoRA in 4 steps.").
- Only when split: how it differs from the others (a LoRA, the steps).
- For `report.html`: "Open it to compare with the original workflow and to read how the rebuilt workflow works."
3. **Changed from the original workflow**: each change that makes the result differ, one bullet each. Nested under it: the reason, when the change alone does not explain itself; what takes the place of something lost. Of what the references say to report, only these are said.
- For `report.html`: "Open it to compare with the original workflow and to read how the rebuilt workflow works." When there is no original: "Open it to read how the workflow works."
3. **Changed from the original workflow** (when there is an original): each change that makes the result differ, one bullet each. Nested under it: the reason, when the change alone does not explain itself; what takes the place of something lost. Of what the references say to report, only these are said.
4. **What else could be changed**, only when there is something: another build with core only (also when a Caution Note already says it); a step that makes in core an input the user would make elsewhere (a depth map from a photo with Depth Anything 3), not added. Write it as "there is also a form that …", not as what you can do ("I can …", "… can also be made").
5. **Other**, only when there is something: a model whose download link was not found; a custom node not installed, whose values were matched from its source.

Expand Down
50 changes: 41 additions & 9 deletions skills/comfyui-readable-node/scripts/canvas.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@
with the core Compare Images (ImageCompare), returns value nodes into their targets or turns them into typed ones,
and merges identical loaders. Removes Preview Image nodes that only show what was loaded.
Reports everything it did. Discards positions, sizes, colors, titles and groups (the author's words are returned separately).
open new <object_info URL or JSON>
A new workflow (no original): only the node definitions are read. src, copy and diff are not used.
src outputs output nodes and the size of each one's upstream
src list [part of type] list of source nodes
src all inputs/outputs, values and mode of every source node at once (instead of many `src node`)
Expand Down Expand Up @@ -355,7 +357,7 @@ def oi(self):
if self._oi is None:
p = self.dir / "object_info.json"
if not p.exists():
raise Stop("not opened yet (run open first)")
raise Stop("not opened yet (run open first; for a new workflow, open new <object_info URL or JSON>)")
self._oi = jload(p)
return self._oi

Expand All @@ -374,9 +376,16 @@ def consume(self, path):
def src(self):
p = self.dir / "src.flat.json"
if not p.exists():
raise Stop("not opened yet (run open first)")
raise Stop("not opened yet (run open first; for a new workflow, open new <object_info URL or JSON>)")
return jload(p)

def original(self):
"""The source, for a move that reads an original: stops when the work was opened with `open new`."""
flat = self.src()
if not self.cfg.get("source"):
raise Stop("no original (opened with `open new`): add nodes with `add <type>`")
return flat

def canvas_path(self, name):
return self.dir / "canvas" / f"{name}.json"

Expand Down Expand Up @@ -3694,10 +3703,18 @@ def do_finish(work, args=()):
if missing:
raise Stop("not finished. Nothing is deleted:\n " + "\n ".join(missing))
root = os.path.abspath(work.dir)
real_root = os.path.realpath(root)

def inside(p):
# the folder that holds the file, with every link followed, must be the working folder or inside it:
# a path spelled inside it can go out through a folder link (W/alias -> elsewhere). The file itself is not
# followed: a file link is deleted as a link, and its target stays
p = os.path.abspath(p)
if p == root:
return False
try:
return os.path.commonpath([root, os.path.abspath(p)]) == root and os.path.abspath(p) != root
parent = os.path.realpath(os.path.dirname(p))
return os.path.commonpath([real_root, parent]) == real_root
except ValueError: # another drive (Windows): outside
return False

Expand Down Expand Up @@ -3727,7 +3744,9 @@ def inside(p):
except OSError:
pass
if os.path.exists(root):
left = sorted(os.path.relpath(os.path.join(dp, f), root) for dp, _, fs in os.walk(root) for f in fs)
# a folder link is named too (os.walk lists it with the folders and does not go into it)
left = sorted(os.path.relpath(os.path.join(dp, f), root) for dp, ds, fs in os.walk(root)
for f in fs + [d for d in ds if os.path.islink(os.path.join(dp, d))])
if not left:
return [f"deleted {len(files)} files. The working folder {root} is empty but could not be removed "
f"(it is the current directory?): remove it from outside"] + note_outside
Expand All @@ -3739,12 +3758,26 @@ def inside(p):

def do_open(work, args):
if len(args) < 2:
raise Stop("open <workflow.json> <object_info URL or JSON>")
raise Stop("open <workflow.json> <object_info URL or JSON>, or for a new workflow (no original): "
"open new <object_info URL or JSON>")
wf_path, oi_src = args[0], args[1]
if work.names():
# one working folder is one job: the export, review and report records of the canvases here would be taken
# for the new job
raise Stop(f"this working folder already holds canvases ({', '.join(work.names())}): open the workflow in "
f"another working folder, named after what it builds (<name>_work). Nothing changed")
oi = CS.load_object_info(oi_src)
work.dir.mkdir(parents=True, exist_ok=True)
jdump(work.dir / "object_info.json", oi)
work._oi = oi
if wf_path == "new":
# a new workflow: only the node definitions; the source is empty and no original is remembered
jdump(work.dir / "src.flat.json", FL.flatten(RW.load({"nodes": [], "links": []}), oi))
work.cfg.pop("source", None)
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
work.cfg["object_info"] = oi_src
work.save_cfg()
return [f"no original: a new workflow, built with the node definitions of {oi_src} ({len(oi)} node types). "
f"Moves that read an original (src, copy, diff) are not used"]
out = []
raw = jload(wf_path)
if AF.is_api(raw):
Expand Down Expand Up @@ -3973,7 +4006,7 @@ def src_node_lines(flat, oi, nid):


def do_src(work, args):
flat, oi = work.src(), work.oi
flat, oi = work.original(), work.oi
if not args:
raise Stop("src <outputs|list|all|node|up|words>")
sub = args[0]
Expand Down Expand Up @@ -4871,8 +4904,7 @@ def _run_cmd(work, line):
work.save_cfg()
return [f"current canvas: {args[0]}"]
if cmd == "diff":
if not work.cfg.get("source"):
raise Stop("not opened yet (run open first)")
work.original()
src, _ = load_source(need_file(work.cfg["source"], "source workflow"), work.oi)
outs = []
for name in work.names():
Expand Down Expand Up @@ -5014,7 +5046,7 @@ def change(cv, work, cmd, args):

def _op_copy(cv, work, args):
nodes = cv.nodes
src = work.src()
src = work.original()
sn = {n["id"]: n for n in src["nodes"]}
for sid in args:
if sid not in sn:
Expand Down
42 changes: 42 additions & 0 deletions tests/test_finish.py
Original file line number Diff line number Diff line change
Expand Up @@ -242,6 +242,48 @@ def test_unknown_files_and_the_folder_are_left(self):
self.assertFalse((self.w / "src.flat.json").exists())
self.assertFalse((self.w / "canvas").exists())

def outside_dir_with_sentinel(self):
outside = self.out / "outside_dir"
outside.mkdir()
sentinel = outside / "sentinel.md"
sentinel.write_text("# S\ntext", encoding="utf-8")
return outside, sentinel

def test_a_note_through_a_folder_link_to_outside_is_kept(self):
outside, sentinel = self.outside_dir_with_sentinel()
(self.w / "alias").symlink_to(outside, target_is_directory=True)
self.do(f"note {self.w / 'alias' / 'sentinel.md'} below 12")
self.export_and_report()
out = self.do("finish")
self.assertTrue(sentinel.exists())
self.assertEqual(sentinel.read_text(encoding="utf-8"), "# S\ntext")
self.assertTrue(any("outside the working folder" in x and "sentinel.md" in x for x in out), out)
# the link itself is left and named: the folder is not called empty
self.assertIn("alias", out[0]); self.assertNotIn("is empty", out[0])
self.assertFalse((self.w / "src.flat.json").exists())

def test_a_canvas_folder_turned_into_a_link_to_outside_is_not_followed(self):
outside, sentinel = self.outside_dir_with_sentinel()
self.export_and_report()
shutil.copy(self.w / "canvas" / "t.json", outside / "t.json")
real = self.w / "canvas"
shutil.move(str(real), str(self.out / "canvas_moved"))
real.symlink_to(outside, target_is_directory=True)
os.environ["CANVAS_KEEP_WORK"] = "1"
listed = self.do("finish")
os.environ.pop("CANVAS_KEEP_WORK")
self.assertFalse(any(x.strip() == "canvas/t.json" for x in listed), listed)
self.assertTrue(any(x.strip() == "src.flat.json" for x in listed), listed)

def test_a_file_link_inside_removes_only_the_link(self):
outside, sentinel = self.outside_dir_with_sentinel()
(self.w / "link.md").symlink_to(sentinel)
self.do(f"note {self.w / 'link.md'} below 12")
self.export_and_report()
self.do("finish")
self.assertTrue(sentinel.exists())
self.assertFalse(self.w.exists())

def test_keep_work_deletes_nothing(self):
self.export_and_report()
os.environ["CANVAS_KEEP_WORK"] = "1"
Expand Down
Loading
Loading