docs: add AGENTS.md, agent skills config, ADRs, and upload helper - #20
Open
gdccyuen wants to merge 5 commits into
Open
docs: add AGENTS.md, agent skills config, ADRs, and upload helper#20gdccyuen wants to merge 5 commits into
gdccyuen wants to merge 5 commits into
Conversation
… script - AGENTS.md: compact instruction file for OpenCode sessions covering repo purpose, verification, build flow, env layering, runtime architecture, conventions, and agent skills config - docs/agents/: issue tracker (local markdown under .scratch/), triage labels (canonical defaults), domain docs (single-context layout) - docs/adr/0001-local-mineru-mode.md: ADR for local MinerU mode via forked image patch, moved from repo root - .gitignore: add .scratch/ for local issue tracking - upload-pdf.sh: helper script to upload a PDF via the API from start to confirm-upload
…w ZIP audit archive ADR 0001 updated: - Status: upstream PR #233 opened - Pitfalls 9-11: files form field, JSON response (not ZIP), response_format_zip=true behavior - Future work: updated to reflect current state ADR 0002 added: - Decision to permanently archive raw MinerU ZIPs to S3 - Covers both local and cloud mode - Storage: S3 + DB column (not DB blob) - 6-step implementation plan (todos 1/6-6/6)
- README (en/zh): add Input Format Recommendation — convert Office files to PDF before uploading. Documents why (docx pipeline flattens tables, drops footers, no full.md; MinerU office backend unreliable; empirical findings from funding-application testing) and the recommended workflow for cost/savings analysis - upload-pdf.sh: fix usage to <API_KEY> [file_path] [namespace] with file_path required, namespace defaulting to 'default'
Live testing against real funding-application .docx files showed the office backend returns empty markdown (only a page-number header survives). EMF vector images are skipped by the image loader and the docx converter emits zero paragraphs/tables even without EMFs. Recommend converting Office files to PDF before uploading.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds agent infrastructure docs and an upload helper script to
knowhere-self-hosted.Changes
Agent skills config (
AGENTS.md+docs/agents/)AGENTS.md— compact instruction file for OpenCode sessions covering repo purpose, verification (smoke-test.sh), local image build flow, env layering gotchas (.env.defaultsvsentrypoint.sh), single-container 3-process runtime, compose services, telemetry, and conventions. Also includes an## Agent skillsblock pointing at the three config docs.docs/agents/issue-tracker.md— local markdown tracker under.scratch/<feature-slug>/docs/agents/triage-labels.md— canonical defaults (needs-triage,needs-info,ready-for-agent,ready-for-human,wontfix)docs/agents/domain.md— single-context layout (CONTEXT.md+docs/adr/).gitignore— added.scratch/so local planning files stay localADRs (
docs/adr/)0001-local-mineru-mode.md— moved from repo root. Updated status to reference upstream PR Ontos-AI/knowhere#233. Added pitfalls 9–11 discovered during live testing against MinerU 3.4.0:filesform field (notfile), default JSON response (not ZIP), andresponse_format_zip=truebehavior.0002-mineru-raw-zip-audit-archive.md— new ADR for permanently archiving raw MinerU ZIPs to S3 with the S3 key injob_results. Covers both local and cloud mode. 6-step implementation plan.Upload helper (
upload-pdf.sh)Shell script that uploads a PDF via the API end-to-end: create job → upload to S3 → confirm upload. Usage:
./upload-pdf.sh <API_KEY> [namespace] [file_path].