I Built a Triage Tool Whose Only Promise Is That Every Item Lands on Exactly One Shelf

说明与用途

Shelf 工具自动将文件夹中的项目按用户定义的项目列表分配到单一的“架子”，并记录原因和来源，确保每个项目只归属一个架子，并在每次构建时验证分区完整性。

问题

Managing a mixed folder of notes, screenshots, and links leads to items being misfiled or duplicated, making it hard to track what belongs to which project or who is waiting on you.

结果

Shelf ensures every item is assigned to exactly one shelf with a documented reason and provenance, preventing silent drops or duplicate filings. The board shows a total count that matches the folder contents, and the build fails if the invariant is violated.

工作流

• 1. Define a project list in a Markdown file (e.g., demo/projects.md).
• 2. Place items (files, images, sidecars) in a folder (e.g., demo/pile).
• 3. Run python shelf.py build --pile demo/pile --projects demo/projects.md.
• 4. Shelf extracts text via OCR or sidecar files, scores against project terms, and assigns each item to a shelf.
• 5. Shelf writes a board.md with shelves, items, reasons, and provenance.
• 6. Shelf runs a partition check that asserts every item lands on a valid shelf, has a reason, and the total count matches the number of items.
• 7. If any assertion fails, the build fails, alerting the user to the misfiled item.

证据

shelf reads the folder, pulls text out of whatever it can, scores that text against a project list you wrote, and writes a board.

来源

It runs on every build and the run fails if it does not hold.

来源

Python 3.10+, standard library only. 51 tests, 124 cross-language verifier asserts, 29 in-page checks, 0 failures.

来源