soia-pkm-alipan-curator

soia-pkm-alipan-curator — Cloud Drive Resource Advisor

Customer-readable description

What this skill can do

Alibaba Cloud Drive Resource Advisor, built on the soia-pkm-alipan-drive-ops atomic operations, provides four types of workflows—inventory/organize/catalog/plan: inventory the cloud drive, organize resources, generate Obsidian collections, incremental Excel master index and family course navigation, and generate a study plan based on the learning situation provided by the user this time

What the customer wants	What the skill will do	What the customer can see
Complete the work covered by this skill	Read the user request, necessary context, and this skill's main workflow, and execute the minimal reliable steps	The customer will see Obsidian/vault file changes, terminal logs, generated artifact paths, and the final receipt.
Missing dependencies, permissions, configuration, or key	Stop actions that require external state, and clearly state what is missing	Installation commands, application addresses, configuration paths, or questions requiring customer confirmation
Execution complete	Summarize successes, skips, failures, file changes, and verification results	A completion receipt that can be copied into a ticket/log

How the customer uses it

State the goal in natural language and provide the necessary inputs: files, URLs, repos, workspaces, proposals, vaults, or platform account status.
The Agent first determines whether this skill is triggered, then checks dependencies, configuration, permissions, and risky actions.
For actions that can be dry-run or previewed, provide a preview first; for actions involving deletion, overwriting, sending, publishing, or writing remote state, seek customer confirmation first.
After execution, verify the actual output; do not substitute "looks successful" for evidence.
The final reply must give the customer a visible summary: what was done, log summary, file changes, issues, and next steps.

Dependencies and installation

Install this skill (single skill):

npx skills add soia-team/soia-open-skills -g -a '*' -s soia-pkm-alipan-curator -y

Configuration conventions:

~/.config/soia-skills/soia-open-skills/soia-pkm/soia-pkm-alipan-curator/config.yml
SOIA_PKM_ALIPAN_CURATOR_CONFIG_FILE=<custom-config-path>

If this skill does not require private configuration, you may skip creating config.yml。
If an API key, cookie, session, provider home, or local path is required, it may only be placed in a private config.yml, process environment, or the provider's own login state; it must not be written into the repository, vault body, or logs.
Strong dependencies, optional dependencies, and third-party skill relationships must be based on this SKILL.md Refer to the subsequent "dependencies / prerequisites / resources / boundaries" description; if it is not clearly stated, first supplement the description or ask the customer, and do not guess.
Third-party skills may only declare dependencies and installation methods; do not directly modify third-party skill files.

Private information and intermediate data

Alibaba Cloud Drive login credentials remain in the provider's own login state or system credential storage; this skill only calls through the atomic layer and does not read, copy, or print secret values.
Move plans, run packages, release manifests, and audit reports are traceable state and are placed in the user state directory; they must not be written into the repository, vault outputs/ or any AI's session directory.
Reconstructable scan parsing and Excel incremental cache go in the user cache directory; downloaded samples and rendering probes go in the OS temporary directory and are cleaned up after success or failure.
Excel, family navigation, and study plans are user deliverables; write only to the user-specified directory, the private configuration directory, or the Downloads fallback directory agreed upon by this skill.
Logs and receipts record only desensitized path roles, counts, hashes, and statuses; do not expose usernames, local private absolute paths, account identifiers, or cloud drive credentials.

Logs and Completion Receipts

Every execution must let the client see the process and the result. Minimum receipt format:

完成：<一句话说明本次完成了什么>。

日志摘要：
- started: <检查到的输入/配置/依赖，不打印秘密值>
- processed: <数量或范围>
- created/updated: <数量或路径>
- skipped/failed: <数量和原因>

文件变化：
- <绝对路径或“未改动文件”>

验证：
- <运行过的检查、命令或人工核对点>

问题与下一步：
- <缺 key / 缺依赖 / 需要客户确认 / 建议下一条命令；没有则写“无”>

Positioning and Dependencies

The layered design of this skill can be compared to the "advisor layer / atomic layer" relationship of huashu-weread-advisor / weread-skills , butdoes not depend on or callthese two third-party skills. All actual underlying commands go through [[soia-pkm-alipan-drive-ops]]; this skill only handlesmethodology and output. The scheduling methodology for study plans inherits from soia-pkm-reading-plan:books are scheduled by word count → videos are scheduled by episode count × per-episode duration, no guessing.

Dependencies must be explained according to the following terms:

Dependency/Reference	Relationship to `soia-pkm-alipan-curator` relationship
`soia-pkm-alipan-drive-ops`	Strong dependency: all cloud drive reads/writes, login, scanning, moving, and renaming go through this atomic layer
`soia-pkm-reading-plan`	Method reuse: the study plan scheduling method follows its principle of "scheduling by real volume"; running it is not required
`huashu-weread-advisor`	Non-dependency: used only as an analogy for the "advisor layer/atomic layer" division of labor; does not read or call this third-party skill
`weread-skills`	Non-dependency: this skill handles Alibaba Cloud Drive resources and does not call the WeRead API
`book-to-skill` / `find-skills`	Non-dependency

Data Sources (the trio, required reading before plan)

Resource map: the collection overview specified by the user via --out <vault>/<catalog-relative-path> (produced by gen_catalog.py ) — only recommendresources already in the cloud drive, do not make the user look for new resources
Learner information: use only the transcript/screenshot/learning situation description explicitly provided by the user this time; do not read or reference private memory, long-term personal profiles, or any personally identifiable information
Plan format: refer to references/plan-template.md(imitating the user's reading plan format: frontmatter + mapping master table + scheduling + pending confirmation to formal)

Subcommand Routing

inventory — Inventory

Recursively scan to the resource root or leaf-level terminal state; stop early only when the user explicitly gives depth, sensitive directories, or aggregation thresholds. Write the checklist to the user-explicitly-specified <vault>/<inventory-relative-path>: record "content · type · suggested action" for each item; after the user decides, hand off to organize. If there is no output parameter, ask first; do not guess the vault directory.

organize — Organize

Execution specification (terminal-state verification at each step; for safety rules see soia-pkm-alipan-drive-ops):

Hard agreement (record first, then act): the move list generated by AI and to be executed — i.e., this skill's scripts/gen_catalog.py of --moves / --roots input file — the standard landing location is ${XDG_STATE_HOME:-$HOME/.local/state}/soia-pkm-alipan-curator/moves/<date>-<batch>.jsonl。--deletes only generates deletion candidates, which must be separately registered in the run package's cleanup_batches, and must not be mixed into the reclassification plan; each prospective cleanup must have an immutable record before writing approved authorization and timezone-aware authorized_at. Before executing cloud drive mv/rmdir , the corresponding manifest must first be written to disk at this path; it is not allowed to act first and add records afterward; operations can be traced afterward via the manifest.

Fixed execution chain for large-scale reorganization: proceed uniformly in the order of merge map → assign numbers (optional) → build reclass → build structure → preflight → audit → dry-run → execute → fresh terminal scan → refresh OB/Excel → publish cloud catalog → final audit ; if any step fails, stop at that step and do not skip the gate to write directly to the cloud drive. Multiple agents may only perform read-only inventory, content review, plan generation, and independent verification in parallel;mkdir / mv / rename / recycle bin deletion / upload and other cloud drive writes are always performed by a single writer, and the batch entry point explicitly uses --max-parallel 1. After the plan and structure contract are merged, the writer must also perform a post-migration terminal-state scan by file_id to confirm that the empty shell actually exists and has 0 children, and then send it to the recycle bin according to the approved manifest. As long as structural writes exist in this round, the run package may only be marked pending_catalog_publishbefore the cloud-side index publication evidence passes, and must not be written in advance as completed。

Stage entry points correspond to the responsibilities of this skill:merge_classification_map.py → assign_resource_numbers.py(only when numbering has been confirmed) → build_reclass_plan.py → build_structure_plan.py → preflight_reclass.py → non- --final of audit_run_bundle.py → apply_reclass.py/apply_reclass_bulk.py dry-run → the same writer plus --execute。audit_structure.py --final and audit_run_bundle.py --final belong to the final audit after a fresh terminal scan, and must not be replaced by a pre-audit. Deletion actions do not belong to this chain: register them to cleanup_batches, and the atomic layer executes them after user authorization and fresh empty-shell verification and reviews the ledger.

Official script table for large-scale reorganization: the following are reusable official entry points; do not write another builder with the same function in the run package, temporary directory, or session.

Stage	Official script	Responsibilities and boundaries
Merge classification conclusions	`scripts/merge_classification_map.py`	Merge the reviewed classifications, classification targets, optional overrides, and inventory into a pending-review TSV map; align by resource ID and reject missing or unknown overrides.
Numbering (optional)	`scripts/assign_resource_numbers.py`	Only when the numbering rule has been confirmed, assign stable prefixes to the resource directories in the map; preserve existing numbers and update the map without modifying the cloud drive.
Generate reclassification plan	`scripts/build_reclass_plan.py`	Generate a deterministic JSONL `mkdir`/`move`/`rename` plan from the reviewed TSV map; only write the local plan and do not call the cloud drive.
Generate structure plan	`scripts/build_structure_plan.py`	Generate an ordered `mkdir` JSONL plan from the structure contract and registered batches; structure batches must be registered to the run package before entering subsequent stages.
Pre-execution precheck	`scripts/preflight_reclass.py`	Perform a fresh read-only cloud-side verification of the registered plan, check the source, target, ID, and parent order, and output a precheck report and `run.json`, the SHA-256 of each registered plan.

Run preflight_reclass.py before, first in run.json.files.preflight_report register a report path that does not yet exist and is relative to the run package; the script refuses to overwrite an existing report and also refuses to write --report to an unregistered location or a location outside the run package. Non-final audit_run_bundle.py will first verify the exact binding of the cleanup authorization,decision=approved and timezone-aware ISO-8601 authorized_at, then call scripts/preflight_gate.py for reconciliation;denied, invalid time, or imprecise binding all fail closed. The executor's --execute branch must explicitly pass --run-dir, and immediately call verify_preflight_gate(Path(args.run_dir), plan_path=Path(args.plan))before the first cloud drive write, confirming that the report has been registered and that passed, the report belongs to the run package, the current execution plan has been registered, and run.json, the SHA-256 of all registered plans, cleanup authorizations, and optional empty-cleanup evidence is unchanged. A pure dry-run may omit --run-dir, but if provided, the gate is likewise enforced. If the plan or manifest changes in any way, retain the old evidence, register the new report path, and re-run preflight; execution must not rely solely on the results of a previous audit.

The reclassification plan and recovery-type executor only accept mkdir、mv、rename. If the plan contains delete、remove or trash, it will be rejected at the parsing stage and output: "Deletion actions should be registered in cleanup_batches and executed by the atomic layer after user authorization + empty-shell verification, and do not enter reclassification recovery/replay"; in this case the cloud drive runner is not invoked. Deletion actions must be executed separately according to the references/run-bundle.md of cleanup_batches contract.

Preflight supports resumable run bundles: read batch by batch the latest record in the result ledger for the same operation key (action_id/op/from/to/file_id), and count as verified / completed only the contiguous chain prefix whose latest status is file_id and for which the current cloud can prove the planned final state with the same already_verified。mv → rename . Chains such as those first verify the final landing point, then roll back in reverse global plan order and replay; a ledger unilaterally claiming success, a wrong ID, an unregistered operation key, or a broken link in the middle must all produce a violation. If a verified empty mkdir is subsequently sent to the recycle bin with user approval, it can only be converted to run.files.empty_cleanup_evidence via the JSONL evidence registered in superseded; the evidence must exactly match the missing target,files=0, and status must exactly belong to removed_to_recycle_bin_verified、removed_to_recycle_bin_and_absence_verified or removed_to_recycle_bin_and_parent_verified_empty, and subdirectories must precede parent directories. The report checked outputs separately ready_actions、already_verified_actions and superseded_actions; the preflight SHA-256 binding covers the current run.json, all registered plans, cleanup authorizations, and registered empty-cleanup evidence. The cleanup result ledger is appendable evidence during execution and cannot be written into the preflight hash; however, final migration conservation must hash the complete ledger history, and truncation or tampering blocks finalization.

Historical debt must not be whitewashed: a cleanup that has already occurred but lacks the original pre-deletion user authorization is not a compliant input for cleanup_batches , and authorized_atmust never be fabricated or backfilled after the fact. It must be registered separately as a run bundle of run.files.cleanup_process_debt within the XDG state, with a classification of only legacy_process_debt or authorization_unproven_execution, and the original plan/result must be retained for final-state-absence/ID conservation reconciliation. The report will give payload_conservation and structural_process_debtseparately: the former may show that the payload has been reconciled, while the latter will still block final completed, and will never grant authorized_missing. Formal cleanup authorizations apply only to future deletions that have not yet been executed. Obsidian retains only the frozen audit and short receipts, and must not copy the runtime debt ledger or its history into vault/outputs; see references/run-bundle.md。

Remove marketing tail: batch-rename away advertising wording in directory names such as "WeChat Official Account: XXX", "[xx.xGB]", "continuously updated", etc.
Remove nesting: when a directory contains only one subdirectory, first determine whether it is a technical package or source dependency referenced by HTML/playlists/subtitles/scripts/config; technical packages, source code, and their dependency directories must be preserved as a whole, without splitting files, numbering, or deleting the shell just because "only one subdirectory remains". Only ordinary business containers may have their contents lifted up one level and the empty shell then deleted.
Delete ads: directories such as "↑↑Subscribe↑↑",800T资源.txt、福利码.txt etc. first enter the candidate deletion list; delete only after obtaining the user's explicit authorization for the rules and scope
Choose the main axis according to the lookup purpose: first select this layer's main axis from dimensions such as topic, use, audience, stage, status, and medium; do not mix dimensions, do not copy historical directories, and do not name by identifiable personal identity
Unified naming: directories at the same level use the same naming strategy; when the user chooses numbered ordering, then also unify the numbering format and step size
First write the partition boundary sentence: adjacent partitions must be judgeable with a single mutual-exclusion rule. For example, when the user maintains both a "course area" and a "library", independent books/independent book collections go to the library, while a course package jointly composed of videos, handouts, and materials stays wholly in the course area; it must not be that some books stay in the course area by topic while other books enter the library by medium
Uncertain items can be isolated for review: only after the user explicitly specifies a to-be-confirmed/archive target, move the unclear items into that target; group by source or uncertainty reason and keep source path records. Handle independent files file by file and course/technical packages as whole packages, and do not break dependency trees for archiving; public skills must not hard-code directory names or numbers

Full-area deep reorganization (inventory→plan→adjudication→batching→index→consumer-side linkage, all six steps of the full process) → required reading references/deep-reorg-playbook.md(distilled from multi-partition practice: SHA1 deletion evidence, same-name different-hash isolation without deletion, consumer-side file_id red line, multi-AI collaboration boundaries, definition of done).

When covering complete first-level partitions, multiple second-level partitions, or when the user points out multiple missed-cleanup directories at once, you must also read references/run-bundle.md. First in ${XDG_STATE_HOME:-$HOME/.local/state}/soia-pkm-alipan-curator/runs/<run-id>/ establish a run bundle unrelated to the AI workspace, then touch the cloud drive. User-named links,未分类/合集/视频/其他 and other weak-semantic large buckets and high-risk roots discovered by inventory are all written into focus_targets; each focus must have content-audit.jsonl true-read/sampling evidence. At wrap-up, first run audit_structure.py --final, then run audit_run_bundle.py --final; only when both the mechanical contract and the AI second review pass may it be called a "super-large module completed".

When encountering LIST_FAIL, empty directories, overwrite uploads, old file_id, duplicate directories, technical dependency trees, partial index stitching, or multi-agent concurrency, first read references/operations-troubleshooting.md. Core red lines:LIST_FAIL is not equal to an empty directory; every command explicitly --driveId; deletion/overwrite must have authorization; the same index file can only have one writer.

Deep classification (used during large-scale refactoring): first read references/classification-methods.md to choose the classification main axis and correct it according to domain examples, then read references/library-method.md to design the library output.

Real content audit: fully list resource roots; for documents read directories and representative chapters, for audio/video read manifests, subtitles/handouts, and metadata, and download minimal samples when necessary; record evidence, confidence, and suggested destination item by item
One layer, one axis: topic, use, audience, stage, status, and medium can only choose one as this layer's main axis; put the other dimensions at lower layers or in index fields
Numbering is configurable and must be closed-loop: only when the user chooses numbered ordering, add to the business classification layer NN_; the business layer is not judged by directory depth; the "main course/practice/Q&A/other" options offered to users within a course also belong to the navigation layer, while chapter files and the technology dependency tree are not numbered. The step size, format, meaning of the pending-confirmation section, and applicable levels are declared by this plan, with no public fixed values. After execution, every declared level must be scanned one by one, the number of missed numbers is 0, and index folding must not be used to conceal missed numbers in the physical directory.
Long-series grouping is configurable and must be closed-loop: when a course, podcast, video, or volume exceeds the user-confirmed single-folder limit, groups are created by original sequence number or content stage; the threshold, group naming, and applicable series are written into this chunk_layers contract, and the public skill must not hard-code "20 episodes" or a specific directory. When the number of groups exceeds 9, the numbering prefix must be uniformly widened (e.g. 010/020/.../100), to avoid name sorting putting 100 before 10 ; two-digit and three-digit prefixes must not be mixed within the same parent directory. When the main media has sidecars such as subtitles, covers, or XML, use count_pattern to count only the main media, but all sidecars must still follow the main media into the same group. After splitting, no loose files remain in the root directory, and the main media in each group does not exceed the limit; peer technical directories must be explicitly declared in exclude , and any other unmatched directories are treated as missed organization; missing numbers in source materials are only recorded, not fabricated. In the final state, flat_series_discovery must also be used to perform a second scan of this scope, discovering over-limit flat directories not written into chunk_layers ; stable semantic buckets such as natural months can only be explicitly exempted through this contract's exclude_path_patterns Explicit exemption
The learning navigation must be closed-loop: when the user chooses the "start here" mode, the plan must declare the guide name and covered levels; every on-shelf learning category must have a guide directory and a verified navigation file. If the partition root itself needs an entry point, write it separately into required_guides, and do not audit only the subcategories under the root while missing the root-level guide; both guide rules must provide a non-empty file_pattern, with files at least 1 byte by default, or min_bytes may be used to raise the threshold; arbitrary miscellaneous files, empty shells, or zero-byte placeholders are not accepted. Upload the guide first, then perform the final-state scan and index; missing any one of these does not count as complete.
Cloud artifacts and the resource map must be verifiable: after key Excel/description files are uploaded, write them into required_artifacts, and use the final-state scan to reconcile precisely by full path, byte count, SHA1, and optional file_id; an upload echo must not be treated as success. Write the OB resource map into resource_maps, declaring one by one the final file_ids that must appear and the explicit url_prefix; only a real Markdown cloud drive link counts as passing, and claiming in the body that it is "directly accessible" or pasting a bare URL does not count as complete.
Miscellaneous packages must be split: take inventory item by item of vaguely named collection directories → promote high-value independently usable resources to the appropriate business category → classify the remainder by the same main axis → before deleting shells, reconcile so the total counts match.
SHA1-level duplicate checking: for same-name/suspected duplicate resources, first perform file-level hash comparison before deciding which copy to delete; do not guess based on similar file names/sizes.
Ad cleanup feature checklist: thousands of TB of resources/scan code to join groups/100,000-degree V chat/XH1080 tail/ultra-low-price cloud drive membership/suspicious exe — delete text-based ones on sight, and for suspicious exe first list them and wait for confirmation.

Artifact output paths (Category C user deliverables)

The Excel master index, family navigation, and study plan are user deliverables, and the disk directories are determined by the following three-level priority:

The path explicitly stated by the user.
Process environment variables or private config.yml in ALIPAN_CURATOR_OUTPUT_DIR。
When neither is present, the default is <用户家目录>/Downloads/soia-pkm-alipan-curator/(Node uses path.join(os.homedir(), 'Downloads', 'soia-pkm-alipan-curator'), Python uses Path.home() / 'Downloads' / 'soia-pkm-alipan-curator'）。

Both Excel entry points recursively create the final output directory; when using the third-level default, a notice is printed to stderr:输出到默认目录 <路径>（可用 --output-dir 或 config ALIPAN_CURATOR_OUTPUT_DIR 覆盖）. It is explicitly forbidden to write these artifacts into the vault root outputs/, any <session-uuid> -named directory, or a cwd-relative path; the output path provided by the user or config must be an absolute path.navigation.json, QA images, and incremental caches are runtime intermediates, placed respectively in the runtime temp directory or the user cache directory, and do not enter the vault delivery directory.

Obsidian collection Markdown (the md artifacts of inventory/catalog) is category D — the product feature is landing in the vault — an exception, and continues to be written to the agreed paths in the collection area; this exception does not apply to Excel, home navigation, or study plans.

catalog — index lands in OB

Invoking this skill's scripts/gen_catalog.py generates from full-disk scan data 00_馆藏总览(browse) + _全文检索/(search), without hand-writing or writing scripts into the vault. After organizing/moving,mustrerun the refresh (especially when a cross-disk change replaces all file_ids), otherwise the index rots.

When rescanning only one root partition, add --merge-existing <现有00_馆藏总览.md>: the generator will replace only that partition's body and statistics rows, and update the full-disk directory/file totals by the difference; other partitions remain unchanged. Incremental scanning must be paired with --roots to add this root partition's file_id, and continue to use --search-dir to refresh the full-text search file for the same-named partition.

Excel output selection

The artifact the user wants	Official entry point	Description
Full-disk/multi-partition collection master index	`scripts/gen_catalog_xlsx.py`	Lightweight master entry + per-partition details; incrementally refreshed by Markdown SHA-256
Parent explanation and course navigation for a single study partition	`scripts/gen_family_nav_xlsx.mjs`	`01_先看这里` + `02_资源导航`; course names are clickable to go directly
Recoverable execution of an approved reclassification plan	`scripts/apply_reclass.py`	Reads a JSONL plan with `action_id` ;`mv`/`rename` must carry `file_id`, and pre-write, final state, and resume are all verified by reading back according to `name → file_id` ; write calls are throttled by default at 2 seconds (`--throttle-ms 0` disables it), rate limiting backs off at 30/60/120 seconds; limited to `--root` and optional `--archive-root`, default dry-run, stop on failure and write a verified ledger
Recoverable execution of large batches of same-source same-target moves	`scripts/apply_reclass_bulk.py`	Uses the same plan/boundary/identity/ledger contract; at most 20 items are merged into one `mv`, reading source and target before and after the batch and recording the final state per action with `file_id` ; write calls are throttled by default at 2 seconds (`--throttle-ms 0` disables it), rate limiting backs off at 30/60/120 seconds; cloud drive writes always have a single writer,`--max-parallel` can only be `1`; default dry-run
Reviewable grouping plan for extra-long series	`scripts/plan_series_chunks.py`	Generates a stable `mkdir`/`mv` plan and exception report from per-file scanning and this run's rule JSON; natural sorting, same-course main media and sidecars follow the group, unmatched files are blocked by default; only generates a plan, does not write to the cloud drive
Numbering, guide, key cloud artifacts, resource map direct links, long-series grouping, and pending-item closed-loop audit	`scripts/audit_structure.py`	Check the entity structure, exact SHA1/bytes, and direct consumer links from the terminal-state scan JSONL and this contract; return a non-zero exit code on failure
Index release closed-loop audit	`scripts/audit_catalog_publish.py`	Check the unified version/time, partition coverage, local and remote SHA1/bytes/file_id, unique files with the same name, zero references to old IDs, and idempotent status from the release manifest in the run package; return a non-zero exit code on failure
Extra-large module run package, item-by-item coverage of the focus directory, batch ledger, and AI review closed loop	`scripts/audit_run_bundle.py`	Check run package path safety, initial and final scans, content evidence for user-named targets, action plan/results, structural audit, and AI review; return a non-zero exit code on failure

preflight_reclass.py and each aliyunpan call of the two reclassification executors goes through the same-repo soia-pkm-alipan-drive-ops/scripts/run_with_env.py startup to load the private login state of that atomic skill. By default, locate it relative to the skills/ where the current script resides; only override the runner when the caller explicitly sets SOIA_ALIPAN_RUNNER . If the runner is missing or cannot start, fail explicitly, and never fall back to bare aliyunpan or output private configuration details.

Do not write one-off builders in the vault, temporary directory, or session artifact directory. For full-disk index parameters, dependencies, data definitions, cloud coverage, and acceptance, see references/catalog-excel.md; for family navigation JSON fields, run commands, upload order, and acceptance, see references/family-navigation-excel.md. Core conventions:

Full-disk output is lightweight 00_阿里云盘馆藏总索引.xlsx + an adjacent per-partition detail workbook; the number of partitions is dynamically determined by _全文检索/*.md .
Each actual release generates release metadata only once, and lets 00_馆藏总览.md, all _全文检索/*.md, the master Excel, all partition Excel files, and the current resource map share the same set of catalog_release_id、index_updated_at、snapshot_at、catalog_schema_version and source_fingerprint. Time must include a time zone; rerunning with identical input must unchanged, and "current time" must not be used to create a new version.
By default, incrementally refresh by the SHA-256 of each _全文检索/*.md ; only rebuild the partition that changed, and do not rewrite unchanged partitions. When the overview or any partition changes, only additionally rebuild the lightweight main entry.
Use --forceonly for first generation or an overall upgrade of generation rules; daily refreshes must not perform full rebuilds without reason.
Parse caches only go into ${XDG_CACHE_HOME:-$HOME/.cache}/soia-pkm-alipan-curator/catalog-xlsx/, not into the vault/repository.
The Excel authoring layer must use the host-provided @oai/artifact-tool; if missing, stop and explain, and do not switch libraries temporarily. During delivery acceptance, add --verify; when soffice is present, pass it in to precompute link display values.
When a partition needs parent-facing concise explanations, filter tables, and direct course links, family navigation input must come from the terminal-state scan; pass --soffice to precompute HYPERLINK display values, avoiding online previews that show only formulas.
Family navigation must be uploaded and reviewed first, then the terminal-state scan and master index performed; otherwise the index will undercount files that were just uploaded.
When a new partition is produced by a verified migration action and a full-disk scan should not be repeated in this round, only use scripts/materialize_catalog_snapshot.py from a complete base file-by-file scan and run.json.batches closed ledger to materialize the partition snapshot; the script rejects cleanup, unclosed actions, incorrect identity, duplicate IDs, and path conflicts. For historical mkdir when the directory ID was not recorded, pass in the --directory-identities, do not guess file_id. Snapshots, empty error sidecars, and provenance go only in the XDG state run package; if this new partition is to be inserted into an existing overview, you must explicitly provide gen_catalog.py --allow-new-partition, and by default it still fails closed.
Before deep organization is complete, run audit_structure.py --scan <scan.jsonl> --contract <contract.json> [--scan-errors <scan.errors>] [--unclear <unclear.jsonl>] --final. You must first confirm that the final-state scan process has exited with exit code 0; you cannot audit a JSONL that is still growing.contract.json only declares the numbered layers selected by the user for this run, root-level/category guides, key cloud artifacts, resource map links, known long-series groupings, the discovery scope for undeclared long series, and optional root items pending confirmation; all thresholds, paths, file_id, URL prefixes, hashes, and semantic bucket exceptions are passed in by the caller from this run's final-state evidence, and the script has no built-in personal directories, real cloud drive IDs, or fixed episode counts. The discovery scope must use a per-file, non-aggregated final-state scan with no no-descend ; aggregated rows, non-empty or missing error sidecars, mismatched key artifacts, or a resource map missing real links will all cause the audit to fail, and zero matches in the category guide or discovery rules also fails by default. Only when it has been confirmed through other evidence that it is indeed empty should the rule-level allow_empty=truebe set; only after independently verifying scan completeness may the CLI's --allow-missing-scan-errors。
A second run of the full-drive generator with the same parameters must return status=unchanged、rebuilt=[]; if it has been uploaded, the remote SHA1/bytes must match the local ones.
Uploading the cloud index after the structure is written is a mandatory closing step, not an optional suggestion. After local generation, you must re-upload the main entry point and all affected partition details, independently record the final file_id/SHA1/bytes and same-name count with ll , then re-check with audit_catalog_publish.py --final ; when the release manifest, remote evidence, version consistency, or proof of zero references to the old file_id is missing,audit_run_bundle.py --final must fail.

How to build a library (browsing/search/curation + classification scheme)(use when selected resources are consolidated into a queryable collection; for templates and fields, see references/library-method.md）：

Collection Overview: full-drive index MOC. Generated with scripts/gen_catalog.py --scan-dir <scan-dir> --out <catalog-output> --url-prefix <drive-url-prefix> [--moves f --deletes f --roots f --heading-pattern REGEX --section-icons JSON --max-heading-depth N] .--url-prefix must be explicitly provided or injected by SOIA_ALIPAN_URL_PREFIX ; the optional --catalog-link/--cards-link/--classification-link is passed in by the user as a vault-relative wikilink target. By default it conservatively displays all directories; when the internal material tree needs to be collapsed, use --heading-pattern to declare business directory rules, for example pass the numbering system ^\d{2}[_.]. The public default uses only neutral folder icons; partition icons are optionally injected via --section-icons . The overview does not lay out individual files; when single-file search is needed, add --search-dir <search-output-dir> --junk <ignored-prefixes>。
Collection Card: one card corresponds to one resource directory on the cloud drive; the minimum fields are type/tags(馆藏)/drive_link, and the remaining fields and card grouping paths are derived from this run's primary classification axis and common queries, with no forced topic/medium/subject/stage/status; if the actual size field is enabled, it must be measured
Bases database（.base）：filter: file.hasTag("馆藏"); views are derived from the primary classification axis confirmed by the user and common lookup questions, for example all collections/by topic/by audience/by medium/card wall, with no hardcoded fixed views
Partition deep classification scheme document: one per partition, including current state/N-type structure/classification rules (for determining placement of future new resources)/change history/to-dos

plan — study plan (high-frequency main scenario)

Input: grade screenshots/learning situation description (e.g. "this is a learner's end-of-term situation, make a holiday plan"). Process:

Diagnosis: Extract scores/rankings/point-loss areas/goals from the transcript (use them directly if they are in the screenshot; if not, ask 1-2 key questions)
Resource mapping: weaknesses → corresponding resources in the cloud drive index, noting "why this resource addresses this point-loss area"
Scheduling: verify video resourcesnumber of episodes and per-episode duration, then work backward from the user's available time, goal priorities, and burden ceiling to create a weekly plan; if these constraints are missing, ask first, and do not preset the number of main threads or age-based burden standards in the public skill
Persist to disk: write to the OB study plan directory, using anonymous codes like YYYY-MM-DD-<学习者代号>-<主题>.md in the filename, with status "pending confirmation", promoted to official after the user signs off

Organization workflow (the four-step closed loop for large-scale restructuring, see references/library-method.md for details)

Plan first: write the classification plan document in full first (current state/N-category structure/classification rules/pending-decision area), frontmatter status: 待拍板, and do not start moving anything without authorization
User adjudication: list difficult items for the user (ambiguous audience/either-or destination/which copy to keep after deduplication), and get sign-off item by item
Execute in batches: batch by "low risk first, cross-library/cross-drive operations later", immediately review each batch after completion (re-run ls against the final state), and keep a move log for operations (jsonl: original path/new path/operation type/timestamp)
Structural closed loop + map/overview refresh + cloud publishing + documentation backfill: after the final-state scan, first run the audit for numbering/navigation/key cloud artifacts/long-series grouping/pending items, and ensure the violation count is 0; then rebuild the affected maps (especially when a cross-drive move changes all file_ids), write the final file_id into resource_maps contract and verify the real Markdown direct links. Then use the same release metadata to generate OB, the master Excel, and the partitioned Excel, re-upload the cloud drive index, and independently verify file_id/SHA1/bytes/unique files with the same name. The wrap-up must update the OB resource map, Excel, cloud drive index, and 01_先看这里in order, and backfill the plan document's change history; if any consumer side is not updated, it does not count as complete

For extra-large modules, add a run-bundle gate on top of the above four steps:run.json all focus_targets in must appear in both the initial scan, the content audit, and the final-state scan; all batch actions must have verified/skipped-with-reason results;structure-audit.json、catalog-publish-audit.json and ai-review.json must both pass; finally run scripts/audit_run_bundle.py --run-dir <run-dir> --final. If there are structural writes but the index has not been published, the status must remain pending_catalog_publish; only after the cloud publishing audit passes is it allowed to change to completed. Runtime evidence stays in XDG state; OB only stores the resource map, frozen audit, and short receipts.

Execution orchestration experience

Decision and execution are layered: the controller only makes review decisions (batch plans/sign-off on difficult items/review of the final state), and the execution agent only runs within the approved scope ls/mv/rename, without changing classification rules on its own
Fixed parallel scope: multiple agents may only parallelize inventory, content review, planning, and verification; merge map, cloud drive writes, and index/OB/Excel/navigation artifact writes are all completed serially by the controller or a designated single writer. Cloud drive writes do not open a second path just because partitions are mutually disjoint,max_parallel is always 1
Parallelism requires a progress dashboard: When multiple agents are concurrently running different partitions, give the main controller a progress dashboard that can be seen at a glance; don't make the user chase the separate outputs of multiple sessions
Two-layer verification of write operations: any mv/rm/rename immediately after completion, verify the result through an independent channel (switch to a fresh ls / use Read instead of Bash); do not trust only the success message returned by the command—there have been cases of "echo pollution" (showing success but actually not executing), corrected by two-layer verification

Checkpoints (must go through user confirmation)

After inventory: give the user the checklist to review first,do not modify the structure without authorization
Before in-depth classification in organize: first show the user the main classification axis, the full-content audit table, and ambiguous items; only after the user decides, generate the move list
Before plan is written to disk: show the resource mapping table first; if the user says "replace X," rearrange it
Involving deletion: always list the items and wait for confirmation

Scenario few-shot

"Here's a screenshot; this is a certain learner's end of term. Give me a holiday study plan" → plan (diagnosis → mapping → scheduling → write to OB)
"A certain learner needs to do kindergarten-to-primary transition, and language has not yet been introduced" → plan (schedule the learning sequence according to existing introductory resources)
"The cloud drive is a mess again, organize it" → inventory → user confirmation → organize → catalog
"This directory has both books and videos; the original classification is not suitable" → organize (really read a sample → choose the main axis such as theme/use → assess whether to change partition boundaries → full audit table → user decision)
"Programming courses, source code, and courseware are mixed together; how should they be divided" → organize (identify course roots by capability domain; do not split media within a course; inventory multi-direction collections set by set)
"What math resources are in the cloud drive" → directly query 00_Collection Overview to answer, no need to scan the drive
"Build a library for the cloud drive to make it easy to find children's learning resources" → catalog (library construction method (browse/search/curate + classification scheme): collection overview + collection cards + Bases + classification scheme)
"Turn the cloud drive Markdown into filterable Excel / update the Excel master index" → catalog (gen_catalog_xlsx.py incrementally generate the master entry + partition details; ordinary refresh does not add --force）
"Make a parent-readable Excel for this course area that can click into courses" → catalog (gen_family_nav_xlsx.mjs; first prepare the final-state JSON according to family-navigation-excel.md )
"Among this pile of resources, which are for learners and which are for caregivers or teachers" → organize (when this time there really is a mix of multiple audiences, choose audience as the main axis: annotate each item in the audit table → ambiguous items await decision → migrate after the decision)