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, providing four types of workflows on top of soia-pkm-alipan-drive-ops atomic operations: inventory/organize/catalog/plan: inventory the cloud drive, organize resources, generate an Obsidian collection, incremental Excel master index and family course navigation, and generate a study plan based on the learning situation provided by the user in this session

Customer Wants	Skill Will Do	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	Install 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

Other recognizable phrasings include "organize cloud drive", "cloud drive inventory", "update cloud drive index", "update Excel master index", "generate family navigation Excel", "build a library for the cloud drive"; browsing, downloading, or uploading a single file is left to soia-pkm-alipan-drive-ops。

State the goal in natural language and provide the necessary inputs: files, URL, repo, workspace, proposal, vault, or platform account status.
For actions that can be dry-run or previewed, provide a preview first; for anything involving deletion, overwriting, sending, publishing, or writing remote state, seek customer confirmation first.

Dependencies and Installation

Installation (recommended: install the entire domain plugin, installing all skills in this repo at once):

claude plugin marketplace add soia-team/soia-open-skills

claude plugin install soia-pkm-vault@soia

If you only want this one skill, you can use the npx route. Note that the skill will land in the shared source of truth ~/.agents/skills; if the plugin is also installed, the same skill will have two indexes and each will drift, so it is recommended to choose one of the two:

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

Configuration conventions:

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

If this skill does not require private configuration, you do not need to create config.yml。
If an API key, cookie, session, provider home, or local path is required, it can only be placed in private config.yml, the process environment, or the provider's own login state; it must not be written into the repo, vault body, or logs.
Third-party skills can only declare dependencies and installation methods, and do not directly modify third-party skill files.

WorkBuddy The loading unit is role-based experts rather than plugins,npx skills add -a '*' cannot cover it, and it needs to be installed separately; see docs/install/workbuddy.md。

Private Information and Intermediate Data

Alibaba Cloud Drive login credentials remain in the provider's own login state or the system credential store; 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 repo, vault outputs/ or any AI's session directory.
Rebuildable scan parsing and Excel incremental cache go in the user cache directory; download 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 user-specified directories, private configuration directories, 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 outputs. 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 WeChat Reading 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 each item as "content · type · suggested action"; 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 persisted to this path; it is not allowed to act first and backfill records later; afterwards, operations can be traced via the manifest.

Fixed execution chain for large-scale reorganization: proceed uniformly in the order 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 adds --execute。audit_structure.py --final and audit_run_bundle.py --final belong to the closing 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; write only 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 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 passed, the report belongs to this run package, the current execution plan has been registered, and run.json, 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 enforced likewise. If there is any change to the plan or manifest, keep the old evidence, register the new report path, and re-run the preflight; execution must not rely solely on the results of a previous audit.

The reclassification plan and recovery executor only accept mkdir、mv、rename. If the plan contains delete、remove or trash, it will be rejected at the parsing stage with the output: "Deletion actions should be registered in cleanup_batches and executed by the atomic layer after user authorization + empty-shell verification; they 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.

The preflight supports breakpoint run bundles: batch by batch, read the latest record for the same operation key ( result ) in theaction_id/op/from/to/file_idledger, and count as verified / completed only the contiguous chain prefix whose latest status is file_id and whose planned final state the current cloud can prove 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; the 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 later sent to the recycle bin with user approval, it may only be converted to run.files.empty_cleanup_evidence via 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 separately outputs 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 will block closure.

Historical debt must not be whitewashed: a cleanup that has already occurred but lacks the original user authorization document from before deletion 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 for run.files.cleanup_process_debt within the XDG state, the classification can only be 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 keeps only the frozen audit and short receipts, and the runtime debt ledger or its history must not be copied into vault/outputs; for details see references/run-bundle.md。

Remove marketing tails: batch-rename away advertising strings in directory names such as "公众号：XXX", "【xx.xGB】", "持续更新", 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 retained 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 then the empty shell deleted.
Delete ads: directories such as "↑↑订阅↑↑", 800T资源.txt, 福利码.txt, etc. first enter the candidate deletion list; delete them only after obtaining the user's explicit authorization of the rules and scope.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 choose the main axis for this level from dimensions such as theme, purpose, 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 sorting, then unify the numbering format and step size
Write the partition boundary sentence first: adjacent partitions must be able to determine placement with one mutually exclusive rule. For example, when the user maintains both a "course area" and a "book library", standalone books/standalone book collections go to the book library, and a course package composed jointly of videos, handouts, and materials stays as a whole in the course area; it must not be that some books stay in the course area by theme while other books enter the book library by medium
Uncertain items can be isolated for review: only after the user explicitly specifies a pending-confirmation/archive target, move the unclear items into that target; group by source or reason for uncertainty and retain source path records. Process standalone files file by file, process course/technical packages as whole packages, and do not break apart dependency trees for archiving; public skills must not hard-code directory names or numbers

Full-area deep reorganization (six-step full workflow: inventory → plan → adjudication → batching → index → consumer-side linkage) → 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 a complete first-level partition, multiple second-level partitions, or when the user points out multiple unorganized directories at once, you must also read references/run-bundle.md. First establish a run bundle unrelated to the AI workspace in ${XDG_STATE_HOME:-$HOME/.local/state}/soia-pkm-alipan-curator/runs/<run-id>/ , 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; every focus must have content-audit.jsonl real-read/sampling evidence. At wrap-up, first run audit_structure.py --final, then run audit_run_bundle.py --final; only after both the mechanical contract and the AI secondary review pass can it be called a "very large module complete".

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 have only 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: list all 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 recommended destination item by item
One level, one axis: theme, purpose, audience, stage, status, and medium may only choose one as the main axis for this level; put the remaining dimensions at lower levels or in index fields
Numbering is configurable and must be closed-loop: only when the user chooses numbered sorting, add to the business classification level NN_; the business layer is not judged by directory depth; the "main course/practice/Q&A/other" options provided for users to choose within a course also belong to the navigation layer, while chapter files and the technical dependency tree are not numbered. The step size, format, meaning of the pending-confirmation area, and applicable levels are declared by this plan, with no common fixed values. After execution, every declared level must be scanned one by one, with 0 missed numbers; index folding must not be used to conceal missed numbers in the actual directory
Long-series grouping is configurable and must be closed-loop: when a course, podcast, video, or volume exceeds the user-confirmed per-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 common skill does 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 prevent name sorting from placing 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; same-level technical directories must be explicitly declared in exclude , and other unmatched directories are regarded as unorganized; missing numbers in source materials are only recorded, not fabricated. In the final state, also use flat_series_discovery to perform a second scan of this scope, and discover 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 selects the "look here first" 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, and files must by default be at least 1 byte, 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 files/descriptions 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; upload echoes must not be treated as success. Write the OB resource map into resource_maps, declaring one by one the final file_id that must appear and the explicit url_prefix; only a real Markdown cloud drive link counts as passing; claiming in the body that it is "directly accessible" or pasting a bare URL does not count as complete
Miscellaneous packages must be split: for vaguely named collection directories, inventory item by item -> promote independently usable high-value resources to the appropriate business category -> classify the remainder along the same main axis -> reconcile before deleting the shell to ensure the total matches
SHA1-level duplicate checking: for resources with the same name or suspected duplicates, perform file-level hash comparison first 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 the QR code to join the group/100,000-degree V message/XH1080 suffix/ultra-low-price cloud drive membership/suspicious exe - delete text-type items on sight; for suspicious exe files, list them first and wait for confirmation

Artifact output path (Category C user deliverables)

The Excel master index, family navigation, and study plan are user deliverables, and the output directory is determined according to the following three-level priority:

A path explicitly stated by the user.
A process environment variable 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, it prompts 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 cwd-relative paths; output paths provided by the user or config must be absolute paths.navigation.json, QA images, and incremental cache are runtime intermediates; place them in the runtime temporary directory or the user cache directory respectively, and do not put them into the vault delivery directory.

Obsidian vault Markdown (the md artifacts of inventory/catalog) is Class D — the product feature itself lands in the vault — as an exception, continue writing to the agreed paths in the vault area; this exception does not apply to Excel, family navigation, or study plans.

catalog — index lands in OB

The scripts/gen_catalog.py of this skill is invoked to generate 00_馆藏总览(browse) + _全文检索/(search) from full-disk scan data, without handwriting or writing scripts into the vault. After organizing/moving,mustrerun the refresh (especially when cross-disk changes replace all file_ids), otherwise the index rots.

When rescanning only one root partition, add --merge-existing <现有00_馆藏总览.md>: the generator replaces only that partition's body and stats lines, and updates the full-disk catalog/file totals by the difference; other partitions remain unchanged. Incremental scanning must be paired with --roots to add the current root partition's file_id, and continue using --search-dir to refresh the full-text search file for the partition of the same name.

Excel output selection

User-requested artifact	Formal entry point	Description
Full-disk/multi-partition vault master index	`scripts/gen_catalog_xlsx.py`	Lightweight master entry point + per-partition details; incremental refresh by Markdown SHA-256
Parent notes and course navigation for a single study partition	`scripts/gen_family_nav_xlsx.mjs`	`01_先看这里` + `02_资源导航`; course names are clickable and 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`, read-back verification by `name → file_id` is performed before writing, at final state, and on resume; write calls are throttled to 2 seconds by default (`--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; up to 20 items are merged into one `mv`, before and after the batch reads the source and target and records each action's final state by `file_id` ; write calls are throttled to 2 seconds by default (`--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 very long series	`scripts/plan_series_chunks.py`	Generates a stable `mkdir`/`mv` plan and exception report from the per-file scan and this rule JSON; natural sorting, same-course main media and sidecars stay in the group, unmatched files are blocked by default; only generates the 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`	From the terminal-state scan JSONL and this contract, check the entity structure, exact SHA1/bytes, and consumer-facing direct links; return a non-zero exit code on failure.
Index release closed-loop audit	`scripts/audit_catalog_publish.py`	From the release manifest inside the run package, 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 state; return a non-zero exit code on failure.
Extra-large module run packages, item-by-item coverage of focus directories, batch ledgers, and the AI review closed loop	`scripts/audit_run_bundle.py`	Check run package path safety, the initial and final scans, evidence of the content of user-named targets, the action plan/results, the structural audit, and the AI review; return a non-zero exit code on failure.

preflight_reclass.py and each of the two reclassification executors' aliyunpan calls are all via the same repository's soia-pkm-alipan-drive-ops/scripts/run_with_env.py startup, to load that atomic skill's private login state. By default, it is located relative to the skills/ where the current script resides; only when the caller explicitly sets SOIA_ALIPAN_RUNNER is the runner overridden. If the runner is missing or cannot start, it fails explicitly and never falls back to a bare aliyunpan or outputs private configuration details.

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

The full output is a lightweight 00_阿里云盘馆藏总索引.xlsx + adjacent per-partition detail workbooks; the number of partitions is dynamically determined by _全文检索/*.md .
Each actual release generates release metadata only once, and makes 00_馆藏总览.md, all _全文检索/*.md, the master Excel, all partition Excels, and the current resource map share the same set of catalog_release_id、index_updated_at、snapshot_at、catalog_schema_version and source_fingerprint. Times must include a timezone; rerunning with the same input must be unchanged, and the "current time" must not be used to create a new version.
By default, refresh incrementally based on the SHA-256 of each _全文检索/*.md ; only the partition that changed is rebuilt, and unchanged partitions are not rewritten. When the overview or any partition changes, only the lightweight master entry point is additionally rebuilt.
Only use --forceon the first generation or when the generation rules are upgraded as a whole; daily refreshes must not perform unjustified full rebuilds.
Parse caches go only into ${XDG_CACHE_HOME:-$HOME/.cache}/soia-pkm-alipan-curator/catalog-xlsx/, not into the vault/repository.
The Excel authoring layer is not bound to a single platform: prefer reusing the host-provided @oai/artifact-tool(richer formatting, with built-in formula error scanning and screenshot previews); when missing, automatically fall back to the built-in openpyxl generic fallback, ensuring that an AI/host without access to that runtime can still produce a valid index with consistent data definitions.--renderer {auto,artifact-tool,openpyxl} explicitly select or force a path;auto(default) prefers an available artifact-tool. Add --verifyduring delivery acceptance; when soffice is present, pass it in to precompute link display values; on the openpyxl path, --soffice is also used to supplement formula error scanning, and when missing, truthfully note that this round of QA did not cover it, and do not pretend it passed scanning.
When a partition needs parent-facing concise explanations, filter tables, and direct course links, the family navigation input must come from the terminal-state scan; pass --soffice to precompute HYPERLINK display values, avoiding online previews showing only formulas.
Upload and review family navigation first, then do the terminal-state scan and master index; otherwise the index will undercount the files just uploaded.
After the home navigation is generated, uploaded, and verified,you must explicitly ask the userwhether to use scripts/check_family_nav_staleness.py register to register the staleness-detection baseline (this is not a hidden step that can be skipped by default), and clearly tell the user the absolute path of the registry; after consent, subsequently run check with a fresh file-level scan to detect suspected staleness. This script only reports differences; it cannot automatically regenerate or upload. See references/family-navigation-excel.md。
When a new partition is produced by an already-verified migration action and this round should not repeat a full-disk scan, only scripts/materialize_catalog_snapshot.py can be used to materialize a partition snapshot from the closed ledger of a full base file-by-file scan and run.json.batches ; the script rejects cleanup, unclosed actions, wrong identity, duplicate IDs, and path conflicts. When historical mkdir does not record the directory ID, pass in the --directory-identitiesobtained from the shallow terminal-state list; do not guess file_id. The snapshot, empty error sidecar, and provenance go only in the XDG state run package; if this new partition is to be inserted into an existing overview, gen_catalog.py --allow-new-partitionmust be explicitly provided; by default it still fails closed.
Run audit_structure.py --scan <scan.jsonl> --contract <contract.json> [--scan-errors <scan.errors>] [--unclear <unclear.jsonl>] --finalbefore deep organization is complete. You must first confirm that the terminal-state scan process has exited and that the exit code is 0; you must not audit a JSONL that is still growing.contract.json only declares the numbered tiers selected by the user this time, root-level/category navigation, key cloud artifacts, resource map links, known long-series groupings, undeclared long-series discovery scope, 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 round's terminal-state evidence, and the script does not hard-code any personal directory, real cloud drive ID, or fixed episode count. The discovery scope must use a file-by-file, non-aggregated, no-descend -free terminal-state scan; aggregated rows, non-empty or missing error sidecars, mismatched key artifacts, or a resource map lacking real links will all cause the audit to fail, and zero matches for category navigation or discovery rules also fail by default. Only set rule-level allow_empty=truewhen it has been confirmed by other evidence that it is truly empty; only after independently verifying scan completeness may you use the CLI's --allow-missing-scan-errors。
Running the full-disk generator a second time with the same parameters must return status=unchanged、rebuilt=[]; if it has already been uploaded, the remote SHA1/bytes must match the local ones.
Uploading the cloud index after structural writes is a mandatory closing step, not an optional suggestion. After local generation, the main entry point and all affected partition details must be re-uploaded, independently ll record the final file_id/SHA1/bytes and the count of same-name items, then use audit_catalog_publish.py --final to re-check; when the release manifest, remote evidence, version consistency, or proof of zero references to old file_id is missing,audit_run_bundle.py --final must fail.

Library construction method (browse/search/curate + classification scheme)(used when selected resources are consolidated into a queryable collection; see templates and fields in references/library-method.md）：

Collection overview: a full-disk index MOC. Generate 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 ; optional --catalog-link/--cards-link/--classification-link is passed in by the user as a vault-relative wikilink target. By default, all directories are conservatively displayed; when the internal material tree needs to be collapsed, use --heading-pattern to declare business directory rules, for example pass ^\d{2}[_.]for a numbering system. 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 retrieval 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, the remaining fields and card grouping paths are derived from this main classification axis and common queries, not forced topic/medium/subject/stage/status; if the actual volume field is enabled it must be measured
Bases database（.base）：filter: file.hasTag("馆藏"); views are derived from the user-confirmed main classification axis and common lookup questions, e.g. all holdings/by subject/by audience/by medium/card wall, without hardcoding fixed views
Partition depth classification scheme document: one per partition, containing current state/N-class structure/classification rules (for determining placement of future new resources)/change history/todos

plan — study plan (high-frequency main scenario)

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

Diagnosis: extract scores/rankings/point-loss points/goals from the transcript (use directly if present in the screenshot, otherwise ask 1-2 key questions)
Resource mapping: weak areas → corresponding resources in the cloud drive index, annotating "why this resource addresses this point-loss point"
Scheduling: for video resources, verifyepisode count and per-episode duration, and schedule the weekly plan backward from the user-provided available time, goal priorities and burden ceiling; 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
Persisting: write to the OB study plan directory, with the filename using YYYY-MM-DD-<学习者代号>-<主题>.md such anonymous codes, status "pending confirmation", and promote to official after the user decides

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

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

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

Execution orchestration experience

Separation of decision and execution: The controller only makes review decisions (approve plans / make the call on ambiguous items / review the final state); execution agents only run within the approved scope ls/mv/rename, and do not change classification rules on their 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 lane just because partitions do not overlap,max_parallel is always 1
Parallelism must provide a progress dashboard: When multiple agents concurrently run different partitions, give the controller a progress dashboard that can be taken in at a glance; do not make the user chase the separate output of multiple sessions
Two-layer verification of write operations: Any mv/rm/rename is immediately verified via an independent channel (switch to ls / use Read instead of Bash) after completion; do not just trust the success message returned by the command—there has been "echo pollution" (displays success but actually did not execute), corrected by two-layer verification

Checkpoints (must pass user confirmation)

After inventory: give the user the checklist to review first,do not change the structure without authorization
Before organizer deep classification: show the user the primary classification axis, the full content audit table, and ambiguous items first; only generate the move list after the user rules
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 some learner's end of term; give me a holiday study plan" → plan (diagnosis → mapping → scheduling → write to OB)
"A learner is about to do the kindergarten-to-primary transition, and language enlightenment hasn't started yet" → plan (schedule the learning sequence according to existing enlightenment resources)
"The cloud drive is a mess again, tidy it up" → inventory → user confirmation → organizer → catalog
"This directory has both books and videos; the original classification doesn't fit" → organizer (really read samples → choose primary axes such as theme/purpose → assess whether to change partition boundaries → full audit table → user ruling)
"Programming courses, source code, and courseware are mixed together; how to divide them" → organizer (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 the child'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 an Excel for this course area that parents can understand and click into courses" → catalog (gen_family_nav_xlsx.mjs; first prepare the final-state JSON according to family-navigation-excel.md )
"Which of this pile of resources are for learners, which are for caregivers or teachers" → organizer (when this pass truly has mixed audiences, choose audience as the primary axis: mark each item in the audit table → ambiguous items await ruling → migrate after ruling)