peter
e137725cab
TEXT_KINDS and TEXT_SUFFIXES now include json/csv, with matching sniff_text_kind branches so both explicit --kind and positional auto-mode work. Added validate_payload's JSON shape check mirroring the server. Updated SKILL.md/docs/llm_posting_helper.md with real usage examples, replacing the stale --as-markdown workaround guidance (kept only for genuinely unstructured code, which still has no dedicated kind). Also fixed an unrelated stale doc line found in the same table: html_full's validation was documented as requiring <!doctype AND <html, but only <html is actually required. Verified via dry-run (explicit --kind, auto-mode, invalid-JSON rejection) and one real end-to-end post through the script against the live dev instance. Added tests/scripts/test_daybook_post.py - 17 tests, plain unittest, zero new dependencies, loaded via importlib since the script isn't a package. Closes the test-coverage question the issue raised. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
123 lines
3.6 KiB
Markdown
123 lines
3.6 KiB
Markdown
# LLM Posting Helper
|
|
|
|
Agents should publish to Daybook with `skills/daybook-posting/scripts/daybook_post.py` instead of hand-building HTTP, JSON, curl, or PowerShell multipart requests.
|
|
|
|
The project also keeps `scripts/daybook_post.py` as a compatibility wrapper.
|
|
|
|
The helper is intentionally zero-dependency and uses only Python's standard library. It works on Windows and Linux.
|
|
|
|
## Configuration
|
|
|
|
Set these as real process/shell environment variables — the helper reads
|
|
`os.environ` directly and has no `.env` file support. Copying values into a
|
|
`.env` file in the working directory does nothing; export/`$env:`/`set`
|
|
them, or set them in your agent harness's own env config.
|
|
|
|
```text
|
|
DAYBOOK_URL=http://127.0.0.1:8001
|
|
DAYBOOK_TOKEN=your-personal-api-token
|
|
DAYBOOK_SOURCE=agent
|
|
```
|
|
|
|
`DAYBOOK_TOKEN` is a personal per-user token, from Settings → Account in the app — not a token shared across users. Override these per environment.
|
|
|
|
## Commands
|
|
|
|
Check the instance:
|
|
|
|
```bash
|
|
python skills/daybook-posting/scripts/daybook_post.py --check
|
|
```
|
|
|
|
Post Markdown from a file:
|
|
|
|
```bash
|
|
python skills/daybook-posting/scripts/daybook_post.py --kind markdown --title "Build Report" --content-file report.md --tags build,report
|
|
```
|
|
|
|
Post Markdown from stdin:
|
|
|
|
```bash
|
|
cat report.md | python skills/daybook-posting/scripts/daybook_post.py --kind markdown --title "Build Report"
|
|
```
|
|
|
|
Post a deck:
|
|
|
|
```bash
|
|
python skills/daybook-posting/scripts/daybook_post.py --kind deck --title "Deployment Plan" --content-file deck.html
|
|
```
|
|
|
|
`deck.html` must contain top-level `<section>...</section>` blocks.
|
|
|
|
Post an image/PDF/binary file:
|
|
|
|
```bash
|
|
python skills/daybook-posting/scripts/daybook_post.py --file diagram.svg --title "Architecture Diagram"
|
|
python skills/daybook-posting/scripts/daybook_post.py --file report.pdf --title "Generated Report"
|
|
```
|
|
|
|
Post CSV or JSON as an interactive table/tree (auto-mode detects the kind
|
|
from the extension; explicit `--kind` works too):
|
|
|
|
```bash
|
|
python skills/daybook-posting/scripts/daybook_post.py results.csv
|
|
python skills/daybook-posting/scripts/daybook_post.py --kind json --title "Run Summary" --content-file summary.json
|
|
```
|
|
|
|
Render other code as a Markdown fenced block instead (no dedicated `code`
|
|
kind yet):
|
|
|
|
```bash
|
|
python skills/daybook-posting/scripts/daybook_post.py --file script.py --as-markdown --title "Generated Script"
|
|
```
|
|
|
|
Dry run:
|
|
|
|
```bash
|
|
python skills/daybook-posting/scripts/daybook_post.py --kind markdown --title "Draft" --content-file report.md --dry-run
|
|
```
|
|
|
|
The artifact URL is printed as the final stdout line.
|
|
|
|
## Validation Guardrails
|
|
|
|
The helper validates common LLM mistakes before sending:
|
|
|
|
| Kind/input | Validation |
|
|
|---|---|
|
|
| `deck` | Must contain `<section`. |
|
|
| `html_fragment` | Must not contain `<!doctype`, `<html`, or `<body`. |
|
|
| `html_full` | Must contain `<html` (a `<!doctype` is recommended, not required). |
|
|
| `markdown` | Must not be blank. |
|
|
| `json` | Must be valid JSON (`json.loads` must succeed). |
|
|
| `.svg` upload | Forces `image/svg+xml`. |
|
|
| `.pdf` upload | Forces `application/pdf`. |
|
|
|
|
## Metadata
|
|
|
|
Use repeatable `--meta key=value` flags:
|
|
|
|
```bash
|
|
python skills/daybook-posting/scripts/daybook_post.py \
|
|
--kind markdown \
|
|
--title "Run Summary" \
|
|
--content-file summary.md \
|
|
--meta run_id=run-001 \
|
|
--meta model=gpt-5.5
|
|
```
|
|
|
|
Or pass a JSON object:
|
|
|
|
```bash
|
|
python skills/daybook-posting/scripts/daybook_post.py --kind markdown --title "Run Summary" --content-file summary.md --meta-json '{"run_id":"run-001"}'
|
|
```
|
|
|
|
## Skill Wrapper
|
|
|
|
A thin LLM-facing wrapper lives at:
|
|
|
|
```text
|
|
skills/daybook-posting/SKILL.md
|
|
```
|
|
|
|
Its key instruction is: do not hand-build requests; use `scripts/daybook_post.py`.
|