soia-pkm-alipan-curator

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

Customer-readable explanation

What this skill can do

Alibaba Cloud Drive Resource Advisor, built on soia-pkm-alipan-drive-ops atomic operations, provides four workflow types—inventory/organize/catalog/plan: inventory the cloud drive, organize resources, generate an Obsidian library, incremental Excel master index and family course navigation, and generate a learning 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 minimum reliable steps	The customer will see Obsidian/vault file changes, terminal logs, generated artifact paths, and the final receipt.
Missing dependencies, permissions, configuration, or keys	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 customers use it

Describe 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-pkm-clip-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 need private configuration, you may skip creating config.yml。
If an API key, cookie, session, provider home, or local path is needed, it may only be placed in a private config.yml, the 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 and the subsequent "dependencies / prerequisites / resources / boundaries" description; if it is not clearly written, add the description first or ask the customer—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 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 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 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 described according to the following terms:

Dependency/Reference	Relationship to `soia-pkm-alipan-curator` relationship to
`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; this third-party skill is not read or called
`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, don't make the user go find 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 a depth, sensitive directory, or aggregation threshold. Write the checklist to the user-explicitly-specified <vault>/<inventory-relative-path>: each item records "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 before acting): the move list generated by AI and to be executed — i.e., this skill's scripts/gen_catalog.py 's --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 entry must have an immutable record before writing approved authorization and time-zone-aware authorized_at. Before executing the 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 later; afterwards, operations can be traced via the manifest.

Large-scale reorganization fixed execution chain: 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 do 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 batch entry points explicitly use --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 sub-items, and then send it to the recycle bin according to the approved manifest. As long as there is structural writing in this round, the run bundle may only be marked pending_catalog_publishbefore the cloud index publication evidence passes, and must not be written in advance as completed。

Stage entry points correspond to this skill's responsibilities: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 → same writer plus --execute。audit_structure.py --final and audit_run_bundle.py --final belong to the closing audit after the fresh terminal scan, and must not be replaced by a pre-audit. The deletion action does not belong to this chain: register it to cleanup_batches, and the atomic layer executes it after user authorization and fresh empty-shell verification and reconciles the ledger.

Large-scale reorganization official script table: the following are reusable official entry points; do not write builders with the same function in the run bundle, temporary directories, or sessions.

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 TSV map pending review; align by resource ID and reject missing or unknown overrides.
Numbering (optional)	`scripts/assign_resource_numbers.py`	Only when the numbering rules have 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 from the reviewed TSV map `mkdir`/`move`/`rename` plan; write only the local plan, 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 bundle before entering subsequent stages.
Pre-execution preflight	`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 the preflight report and `run.json`, as well as the SHA-256 of each registered plan.

Run preflight_reclass.py Before running, first, in run.json.files.preflight_report register a not-yet-existing report path relative to the run bundle; the script refuses to overwrite an existing report and also refuses to write --report to an unregistered location or outside the run bundle. Non-final audit_run_bundle.py will first validate the cleanup authorization's exact binding,decision=approved and time-zone-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 before the first cloud drive write call verify_preflight_gate(Path(args.run_dir), plan_path=Path(args.plan)), confirm that the report has been registered and passed, that the report belongs to this run bundle, that the current execution plan has been registered, and that 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 likewise enforced. If there is any change to the plan or manifest, retain the old evidence, register the new report paths, and re-run preflight; execution must not rely solely on the previous audit results.

Reclassification plans and recovery-type executors accept only 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"; at this point 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: batch by batch, read from the result ledger the latest record for the same operation key (action_id/op/from/to/file_id), and only count as verified / completed the continuous chain prefix whose latest status is file_id and for which the current cloud side can prove the planned final state with the same already_verified。mv → rename , etc. Chains are first verified at the final landing point, then rolled back in reverse global-plan order and replayed; a ledger unilaterally claiming success, a wrong ID, an unregistered operation key, or a broken chain in the middle must all produce a violation. If a verified empty mkdir is later 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 must not be written into the preflight hash; however, final migration conservation must hash the complete ledger history, and truncation or tampering blocks closure.

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 run.files.cleanup_process_debt in a run bundle within XDG state, and its 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 retains only frozen audits and short receipts, and the runtime debt ledger or its history must not be copied into the vault/outputs; for details see references/run-bundle.md。

Remove marketing tails: advertising phrases such as "公众号：XXX", "【xx.xGB】", "持续更新", etc. in directory names are batch-renamed away
Remove nesting dolls: when a directory contains only one subdirectory, first determine whether it is a technical package or source-code dependency referenced by HTML/playlists/subtitles/scripts/configuration; technical packages, source code, and their dependency directories must be preserved as a whole—do not split files, do not number them, and do not delete the shell merely 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,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 topic, 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 using 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, while 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 topic 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. Handle standalone files file by file, handle 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 process: inventory → plan → adjudication → batching → index → consumer-side linkage) → required reading references/deep-reorg-playbook.md(distilled from multi-partition practice: SHA1 deletion evidence, isolation without deletion for same-name different-hash items, consumer-side file_id red lines, 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 when 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 does not equal 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 suggested destination item by item
One level, one axis: topic, 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 single-folder limit, create groups by original sequence number or content stage; the threshold, group naming, and applicable series are written into this chunk_layers contract; 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 avoid name sorting placing 100 before 10 ; within the same parent directory, two-digit and three-digit prefixes must not be mixed. 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 considered missed organization; 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 reviewable: 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; upload echoes must not be treated as success. The OB resource map is written into resource_maps, declaring one by one the final file_id and explicit url_prefixthat must appear; only real Markdown cloud drive links count as passing, and neither claims in the body that something is "directly accessible" nor pasted bare URLs 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 same-name/suspected duplicate resources, 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 code to join groups/100,000-degree V message/XH1080 tail/ultra-low-price cloud drive membership/suspicious exe - delete text-type items on sight; for suspicious exe, 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.
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, prompt 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 configuration must be an absolute path.navigation.json, QA images, and incremental cache are runtime intermediates, placed respectively in the runtime temporary 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, family navigation, or study plans.

catalog — index lands in OB

Invoke this skill's scripts/gen_catalog.py generates from full-disk scan data 00_馆藏总览(browse) + _全文检索/(search), do not hand-write, do not write scripts into the vault. After organizing/movingmustrerun refresh (especially when cross-disk causes all file_id to change), 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 of the same-named partition.

Excel output selection

The artifact the user wants	Formal entry point	Description
Full-disk/multi-partition collection master index	`scripts/gen_catalog_xlsx.py`	Lightweight master entry + per-partition details; incremental refresh 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`	Read JSONL plan with `action_id` ;`mv`/`rename` must carry `file_id`, before writing, 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` off), rate limiting backs off at 30/60/120 seconds; limited to `--root` and optional `--archive-root`, default dry-run, stop on failure and write verified ledger
Recoverable execution of large batches of same-source same-target moves	`scripts/apply_reclass_bulk.py`	Use the same plan/boundary/identity/ledger contract; merge up to 20 items into one `mv`, read source and target before and after the batch and record the final state per action with `file_id` ; write calls are throttled by default at 2 seconds (`--throttle-ms 0` off), rate limiting backs off at 30/60/120 seconds; cloud drive writes are always single-writer,`--max-parallel` can only be `1`; default dry-run
Reviewable grouping plan for extra-long series	`scripts/plan_series_chunks.py`	Generate a stable `mkdir`/`mv` plan and exception report from per-file scanning and this 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`	From the final-state scan JSONL and this contract, check the entity structure, exact SHA1/bytes, and consumer-side direct links; return a non-zero exit code on failure
Index release closed-loop audit	`scripts/audit_catalog_publish.py`	From the manifest published inside the run package, check 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; 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, evidence for user-named target content, action plan/results, structural audit, and AI review; return a non-zero exit code on failure

preflight_reclass.py and each of the two reclassification executors’ aliyunpan calls are all made through 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 relatively located from the skills/ where the current script is located; only when the caller explicitly sets SOIA_ALIPAN_RUNNER does it override the runner. If the runner is missing or cannot start, it will fail explicitly and never fall back to a bare aliyunpan or output private configuration details.

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

The full output is a 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 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. Time must include a time zone; rerunning with the same input must be unchanged, and "current time" must not be used to create a new version.
By default, refresh incrementally by 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 is additionally rebuilt.
Use --forceonly for initial generation or a full upgrade of the generation rules; daily refreshes must not trigger a full rebuild without reason.
The parse cache goes 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 preview); when missing, automatically fall back to the built-in openpyxl generic fallback, ensuring that AI/hosts without access to that runtime can still produce valid indexes with consistent data definitions.--renderer {auto,artifact-tool,openpyxl} explicitly select or force a certain path;auto(default) prefer the available artifact-tool. During delivery acceptance, add --verify, and when soffice is available, pass it in to precompute the link display values; under the openpyxl path, --soffice is also used to fill in formula error scanning. When missing, truthfully note that this round of QA did not cover it, and do not pretend it was scanned and passed.
When a partition needs parent-facing concise explanations, filter tables, and course direct links, the family navigation input must come from the final-state scan; pass --soffice to precompute HYPERLINK display values, avoiding online previews showing only formulas.
Upload and review family navigation first, then do the final-state scan and master index; otherwise the index will undercount the files just uploaded.
After the home navigation is generated, uploaded and verified, you can use scripts/check_family_nav_staleness.py register to register the baseline, and subsequently run with a fresh file-level scan check to detect suspected staleness; this script only reports differences and cannot automatically regenerate or upload; see references/family-navigation-excel.md。
When a new partition is produced by a verified migration action and a full scan should not be repeated in this round, you can only use scripts/materialize_catalog_snapshot.py to materialize a partition snapshot from a complete base with a file-by-file scan and a closed ledger of run.json.batches . The script rejects cleanup, unclosed actions, wrong identity, duplicate IDs and path conflicts. For historical mkdir when the directory ID is not recorded, pass in the --directory-identitiesobtained from the shallow terminal-state list; do not guess the file_id. Snapshots, empty error sidecars and provenance are only placed in the XDG state run package; if you want to insert this new partition into the 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 terminal-state scanning process has exited and its exit code is 0; you must not audit a JSONL that is still growing.contract.json only declares the numbered layers selected by the user for this run, the root-level/category navigation, key cloud artifacts, resource map links, known long-series groupings, the discovery scope of undeclared long series, and the optional root to be confirmed; all thresholds, paths, file_id, URL prefixes, hashes and semantic bucket exceptions are passed in by the caller from the terminal-state evidence of this run, and the script does not hardcode any personal directories, real cloud drive IDs or fixed episode counts. The discovery scope must use a terminal-state scan that is file-by-file, without aggregation, and without no-descend . Aggregated lines, a nonempty or missing error sidecar, 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 will also fail by default. Only when it has been confirmed through other evidence that it is indeed empty, set the rule-level allow_empty=true; only after independently verifying scan completeness can you use the CLI's --allow-missing-scan-errors。
Running the full-drive generator a second time 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 structural writes is a mandatory closing step, not an optional suggestion. After local generation, you must re-upload the main entry and all affected partition details, and independently ll to record the final file_id/SHA1/bytes and same-name count, then use audit_catalog_publish.py --final to recheck; if 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.

Library construction method (browse/search/curate + 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. Use 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] to generate.--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 you need to collapse internal material trees, use --heading-pattern to declare business directory rules, for example, pass ^\d{2}[_.]for the numbering system. The public default uses only neutral folder icons, and partition icons are optionally injected via --section-icons . The overview does not list 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, and the remaining fields and card grouping paths are derived from this run's main classification axis and common queries, with topic/medium/subject/stage/statusnot mandatory; if actual volume fields are enabled, they must be measured
Bases database（.base）：filter: file.hasTag("馆藏"); Views are derived from the user-confirmed primary classification axis and common lookup questions, e.g. all holdings/by subject/by audience/by medium/card wall; do not hardcode fixed views
Partition depth classification scheme document: one per partition, containing current state/N-category structure/classification rules (for determining placement of future new resources)/change history/to-dos

plan — study plan (high-frequency primary scenario)

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

Diagnosis: extract score/ranking/lost points/goal 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, annotated with "why this resource addresses this lost-point area"
Scheduling: for video resources, verifyepisode count and per-episode duration, and schedule the weekly plan backwards from the user-provided available time, goal priorities, and burden ceiling; if these constraints are missing, ask first, and do not presuppose the number of main threads or age-based burden standards in the public skill
Persist to disk: write to the OB study plan directory, with filename using YYYY-MM-DD-<学习者代号>-<主题>.md anonymous codes such as this, status "pending confirmation", promoted after the user gives the final decision

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

Plan first: first write the classification scheme document in full (current state/N-category structure/classification rules/pending-decision area), frontmatter status: 待拍板, and do not begin moving on your own initiative
User adjudication: list difficult items (ambiguous audience/two-way destination choice/which copy to keep after deduplication) for the user, and decide each one by one
Batch execution: batch by "risk from low to high, cross-library/cross-drive operations placed later"; after each batch is completed, immediately review (re-run 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 for numbering/guide/key cloud artifacts/long-series grouping/pending-confirmation items, with a violation count of 0; then rebuild the affected maps (especially when a cross-drive move causes all file_id values to change), write the final file_id into resource_maps contract and verify the actual Markdown direct links. Then use the same release metadata to generate OB, the master Excel, and partition Excel, re-upload the cloud index, and independently verify file_id/SHA1/bytes/unique same-name files. Closing 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 a structural write 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 stores only the resource map, frozen audit, and short receipts.

Execution orchestration experience

Layering of decision-making and execution: The main controller only makes review decisions (approving plans / making the call on difficult items / reviewing the final state), and execution agents only run within the approved scope ls/mv/rename, without changing classification rules on their own
Parallel scope is fixed: 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 main controller or a designated single writer. Cloud drive writes do not open a second lane just because partitions are mutually disjoint;max_parallel is always 1
Parallelism must provide a progress dashboard: When multiple agents run different partitions concurrently, give the main controller a progress dashboard that can be read at a glance; do not make the user chase the separate outputs of multiple sessions
Two-layer verification for write operations: Any mv/rm/rename must be verified immediately after completion 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 has been "echo pollution" (showing success but not actually executing), and two-layer verification is what corrects it

Checkpoints (must pass user confirmation)

After inventory: give the user the checklist to review first,do not change the structure without authorization
Before deep classification in organize: show the user the main classification axis, the full content audit table, and ambiguous items first; 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", redo the arrangement
When deletion is involved: 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 preschool-to-primary transition, but language enlightenment has not started yet" → plan (arrange the learning sequence according to existing enlightenment resources)
"The cloud drive is messy again, tidy it up" → inventory → user confirmation → organize → catalog
"This directory has both books and videos; the original classification is not suitable" → organize (really read samples→choose the main axis such as theme/use→assess whether to change partition boundaries→full audit table→user decision)
"How should programming courses, source code, and courseware mixed together be separated" → 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 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 point + partition details; a normal refresh does not add --force）
"Make an Excel for this course area that parents can understand and click into the course" → catalog (gen_family_nav_xlsx.mjs; first prepare the final-state JSON according to family-navigation-excel.md )
"Among these resources, which are for the learner, and which are for caregivers or teachers" → organize (when there is indeed a mix of multiple audiences this time, choose audience as the main axis: mark each item in the audit table→ambiguous items awaiting decision→migrate after the decision)